xbintsc 0.5.6 → 0.5.21

package/doc/zh-CN/node-unimplemented.md

@@ -1,141 +1,6 @@
-# xbintsc Node 扩展未实现功能
+# Node 扩展：未实现（已迁移）
 
-> 语言 / Language：[English](../node-unimplemented.md) | **简体中文**
-
-本文档基于对 Node 扩展源码（`src/extensions/node/`）与 C 运行时（`runtime/ext_node/`）的逐文件核对整理，列出 **Node 扩展当前未实现 / 缺失** 的功能。
-
-> 相关文档：
-> - 核心语言能力见 [implemented.md](implemented.md) / [unimplemented.md](unimplemented.md)
-> - Node 扩展已实现部分见 [node-implemented.md](node-implemented.md)
-
----
-
-## 1. `fs` 模块未实现
-
-`fs` 现在实现了**同步** API 表面（文件、目录、描述符、元数据、链接、`cp`、`glob`、`Dir`、`constants`），`fs/promises` 将每个同步函数包进已 settle 的 Promise（见 [node-implemented.md](node-implemented.md)）。其余仍未实现，因为 xbintsc 的 `fs` **没有异步 I/O 调度器后端**（核心事件循环已提供定时器与套接字）：
-
-| 未实现 API | 类别 |
-| --- | --- |
-| `readFile` / `writeFile` / `appendFile` / `open` / `close` / `read` / `write` / `stat` / … | 回调式异步文件操作（`fs/promises` 提供 Promise 形式） |
-| `createReadStream` / `createWriteStream` | 流式读写 |
-| `watch` / `watchFile` | **真正的**文件监听：函数存在但返回对象从不触发（无 inotify/kqueue 后端） |
-| `openAsBlob`、`statfs` 回调形式、`rmdir` 的 `maxRetries` / `retryDelay` | 需异步重试的杂项选项 |
-| `glob` 的 `exclude` / `follow`、`cp` 的 `filter` | 选项回调 |
-
-### 1.1 读取语义缺口
-
-- `readFileSync` 支持编码选项（默认/`utf8`/`ascii`/`latin1`/`binary`/`hex`/`base64`/`base64url`），但默认**不返回 `Buffer`**：即使提供了 `Buffer`（以普通对象模拟），`readFileSync` 仍以字符串返回。要读取原始字节请显式指定。
-- 未实现 `utf16le` / `ucs2` 解码（按文本返回字节）。
-- `watch` / `watchFile` / `unwatchFile` 返回 API 形态的发射器对象，`.close()` / `.on()` 方法存在但**不会触发**事件。
-- `Dir.read(cb)` / `Dir.close(cb)` 与 `FileHandle` 异步方法都会**同步**完成（回调/Promise 立即被调用）。
-- `mkdtempSync` 总是向前缀追加 6 个随机字符（不要求以 `XXXXXX` 结尾）。
-- `globSync` 支持 `*`、`?`、`[...]`、`**`，但不支持 `exclude` 回调与 `follow`；`**` 不跟随符号链接（与 Node 默认一致）。
-- `cpSync` 的符号链接处理在常见场景下与 Node 一致，但不支持 `verbatimSymlinks`。
-- 平台差异：Windows 上 `readlinkSync` 抛 `ENOSYS`，`chmodSync` / `lchmodSync` / `chownSync` / `lchownSync` / `fchmodSync` / `fchownSync` 为空操作；`statfsSync` 在 Windows/AIX/Sun 返回全零字段；`lutimesSync` 在 macOS/Windows 退化为 `utimesSync`。
-
----
-
-## 2. 其它 Node 模块完全未实现
-
-以下 Node 内置模块没有任何对应扩展 / 内置函数（`fs` / `fs/promises` / `path` / `os` / `process` / `buffer` / `stream` / `dgram` / `http` / `events` / `util` / `querystring` / `assert` / `test` 已实现，`crypto` / `url` / `child_process` / `zlib` / `stream/promises` / `worker_threads` 部分实现，见 [node-implemented.md](node-implemented.md)）：
-
-| 模块 | 说明 |
-| --- | --- |
-| `https` | TLS 版 HTTP |
-| `readline` | 命令行读取 |
-| `tls` / `cluster` / `vm` / `os`（部分）等 | 其余未列出的模块 |
-
-> `crypto`（仅 `createHash`，现支持流式 API）、`url`（仅 `pathToFileURL` / `fileURLToPath`）、
-> `child_process`（仅 `spawnSync`）、`zlib`（仅 `createGzip`）与
-> `worker_threads`（仅 `Worker` / `isMainThread` / `workerData` / `parentPort`）目前为部分实现。
-
----
-
-## 3. Node 全局对象 / 命名空间
-
-| 未实现 | 说明 |
-| --- | --- |
-| `global` / `globalThis` | 无 |
-| `__dirname` / `__filename` | 无 |
-| `require` / `module` / `exports` | 仅限 `node_modules` 内的包（打包器会降级）；用户代码需使用 ESM `import` |
-| 未 `import` 的 `fs.readFileSync(...)` | ✗ 不支持。`fs` 不是全局对象；请先导入（`import fs from "fs"` 或 `import * as fs from "node:fs"`），之后 `fs.readFileSync(...)` 会下降为该模块的运行时符号。 |
-
-Node 模块通过裸名称或 `node:` 前缀的 `import` 引入（`import { readFileSync } from "fs"`、`import path from "path"`、`import { platform } from "node:os"`）。具名与命名空间导入都会解析到扩展模块的运行时入口。
-
-已支持的命名空间调用：`path.*`、`os.*`、`process.*`、`fs.*`、`fs/promises.*`（方法）、`child_process.*`、`crypto.*`、`url.*`（需先导入；`path`/`os`/`process` 也可使用全局名），以及基于分发器的 `Buffer.*`、`stream.*`、`net.*`、`dgram.*`、`http.*` 和 `process.platform` / `process.argv` 等属性。`Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` / `Buffer` 亦可用作全局构造函数。
+本页已迁移到 [Node 扩展：未实现](./unimplemented/node.md)。Node 文档现在按模块拆分在
+`doc/zh-CN/unimplemented/node/` 下。
 
----
-
-## 4. 异步 / 事件循环模型
-
-已实现部分：
-
-- 核心事件循环 `runtime/xt_loop.c`（`select(2)` 反应堆），`net` / `dgram` / `http` 均构建于其上。
-- `Promise`、`async` / `await` 已可用（见核心文档），`fs/promises` 返回 Promise。
-- 定时器已作为全局函数提供：`setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` 运行在核心反应堆上，并在仍有定时器时保持进程存活。
-- 提供独立的 `EventEmitter`（`events` 模块，同时也是全局构造函数）；流与套接字额外具备内部发射器方法（`on` / `addListener` / `once` / `off` / `removeListener` / `emit`）。
-
-仍未实现：
-
-- `setImmediate` / `queueMicrotask` 以及 Node 的 `Timeout` 对象（`setTimeout` 返回数字 id）。
-- 真正的异步 I/O 调度：`fs/promises` 实质是同步操作的即时 settle 包装，不会在等待 I/O 时让出。
-- 流与套接字的内置 `once` 等同 `on`（不具「触发一次后移除」语义）；`events` 模块的 `EventEmitter` 实现了真正的 `once`。
-- `net` 的 `connect` 为阻塞式；HTTP 响应要求 `Connection: close`，不做 keep-alive / 分块传输 / 流水线复用。
-
----
-
-## 5. Bun 扩展未实现
-
-设计文档中提到的 `Bun.file` 等 Bun API 仅作为扩展机制的设计示例，**尚未实现**：
-
-- 无 `bun` 扩展目录、无 Bun 内置函数、无 Bun C 运行时。
-- `src/extensions/` 下目前只有 `node` 一个平台扩展（外加核心扩展）。
-
----
-
-## 6. 速查：Node 扩展未实现清单
-
-```
-已实现（fs）：完整同步表面 —— readFileSync（含编码）、readTextFile、
-              writeFileSync、appendFileSync、existsSync、readdirSync（withFileTypes/recursive）、
-              mkdirSync、rmSync、unlinkSync、rmdirSync、renameSync、copyFileSync、cpSync、
-              realpathSync、statSync、lstatSync、statfsSync、accessSync、chmodSync、lchmodSync、
-              chownSync、lchownSync、truncateSync、utimesSync、lutimesSync、mkdtempSync、
-              linkSync、symlinkSync、readlinkSync、opendirSync（Dir）、globSync、watch、
-              watchFile、unwatchFile、constants、
-              openSync、closeSync、readSync、writeSync、readvSync、writevSync、fstatSync、
-              fsyncSync、fdatasyncSync、ftruncateSync、fchmodSync、fchownSync、futimesSync
-已实现（fs/promises）：readFile、writeFile、appendFile、mkdir、readdir、rm、unlink、
-                      rmdir、rename、copyFile、cp、realpath、stat、lstat、statfs、access、
-                      open（FileHandle）、chmod、lchmod、chown、lchown、truncate、utimes、
-                      lutimes、link、symlink、readlink、mkdtemp、opendir、glob、watch、constants
-已实现（其它模块）：path（join/resolve/normalize/dirname/basename/extname/isAbsolute/relative）、
-                    os（platform/arch/type/release/endianness/homedir/tmpdir/hostname/totalmem/freemem/cpus）、
-                    process（cwd/exit/uptime/hrtime/getuid/platform/arch/pid/ppid/argv/env/version/title）、
-                    buffer（from/alloc/isBuffer/byteLength/concat/compare + 实例方法）、
-                    stream（Readable/Writable/Duplex/Transform/PassThrough、pipe）、
-                    net（createServer/connect/isIP + Server/Socket）、
-                    dgram（createSocket + bind/send/close/address）、
-                    http（createServer/request/get + req/res）、
-                    events（EventEmitter：on/once/off/emit/listeners/listenerCount/eventNames）、
-                    util（format/inspect/isDeepStrictEqual/inherits/promisify + isX）、
-                    querystring（parse/stringify/escape/unescape）、
-                    crypto（createHash + 流式 API，SHA-1/SHA-256）、
-                    url（仅 pathToFileURL/fileURLToPath）、
-                    child_process（仅 spawnSync）、
-                    zlib（仅 createGzip）、stream/promises（仅 pipeline）、
-                    worker_threads（仅 Worker/isMainThread/workerData/parentPort）
-
-未实现（fs）：回调式异步文件操作（readFile/writeFile/appendFile/open/read/write/close）、
-              createReadStream/createWriteStream、真正的文件监听（watch/watchFile 对象从不触发）、
-              glob exclude/follow、cp filter、utf16le 解码、readFileSync 返回 Buffer
-
-未实现（其它模块）：https、readline、tls、cluster、vm
-
-未实现（全局/命名空间）：global/globalThis、__dirname、__filename、
-                        require/module/exports、fs.readFileSync(...) 命名空间调用
-
-未实现（异步）：setImmediate / queueMicrotask、真正异步 I/O 调度、keep-alive
-
-未实现（平台）：Bun 扩展（仅设计示例）
-```
+> 语言 / Language：[English](../node-unimplemented.md) | **简体中文**

package/doc/zh-CN/plan-require-node-modules.md

@@ -9,7 +9,7 @@
 > `__dirname` / `__filename`、`Object.defineProperty` getter 形式。详见下文 4.x 与 `unimplemented.md`。
 >
 > 目标版本：0.4.x
-> 关联文档：[unimplemented.md](./unimplemented.md) 第 4 节（模块系统）、[implemented.md](./implemented.md) 第 3.4 节
+> 关联文档：[unimplemented/modules.md](./unimplemented/modules.md)（模块系统）、[implemented/modules.md](./implemented/modules.md)
 
 ## 1. 背景与现状
 
@@ -223,7 +223,7 @@ hasModuleSyntax(entry)  ||  entryAstContainsRequire(entry)
 | **P4** | require 调用点重写 + 诊断（4.7） | 单测：node_modules 内重写为 `__load`，外部保持报错 |
 | **P5** | ESM→CJS 互操作 default/named/namespace（4.6） | 差分测试：与 Node 输出一致（default 函数、命名导出、`__esModule`） |
 | **P6** | 扩展模块 / 可选：`require(esm)`、JSON 模块 | 按需 |
-| **P7** | 文档更新：implemented / unimplemented 第 4 节、README | 文档评审 |
+| **P7** | 文档更新：implemented / unimplemented 的 modules 页面、README | 文档评审 |
 
 每个阶段都应保持现有测试全绿；P0 单独可合入。
 
@@ -237,13 +237,13 @@ hasModuleSyntax(entry)  ||  entryAstContainsRequire(entry)
 | `src/driver/bundler/graph.ts` | 格式判定、收集 `require` 依赖、递归加载 |
 | `src/driver/bundler/merge.ts` | CJS 工厂包装、注册/加载语句注入、require 重写、互操作、依赖表 |
 | `src/driver/bundler/cjs.ts`（新增） | 加载器源码字符串 + 工厂/依赖表/DepsMap 的 AST 构造 helper |
-| `src/driver/compiler.ts` | `isModule` 扩展（4.8），`cacheText` 覆盖新注入代码 |
+| `src/driver/frontend.ts` | `isModule` 扩展（4.8），`cacheText` 覆盖新注入代码 |
 | `src/codegen/generator/context.ts` | `reportRequireUse` 文案更新（node_modules 限定） |
 | `tests/driver/bundler-resolve.test.ts` | 解析/格式/条件单测 |
 | `tests/driver/bundler-cjs.test.ts`（新增） | 工厂包装与重写单测 |
 | `tests/e2e/npm-modules.test.ts` | CJS 包 e2e + 差分 |
 | `tests/parser/*` | P0 回归 |
-| `doc/implemented.md`、`doc/unimplemented.md`、`doc/zh-CN/*` | 第 4 节状态更新 |
+| `doc/implemented/modules.md`、`doc/unimplemented/modules.md`、`doc/zh-CN/*` | 模块状态更新 |
 
 ## 7. 测试计划
 

package/doc/zh-CN/requirements.md

@@ -44,6 +44,12 @@ build/app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected
 Windows 发布包面向 **MSVC ABI**：clang 使用 Windows SDK
 以及 MSVC 的 C/C++ 运行库与头文件。
 
+可选优化特性额外依赖两个工具：
+
+- `--lto` 需要 **lld**（`-fuse-ld=lld`）；上面的 LLVM 安装包已包含。
+- `--pgo-use` 需要 **llvm-profdata** 合并 `.profraw`。驱动优先使用 clang
+  旁边的副本，可用 `xbintsc_LLVM_PROFDATA` 覆盖。
+
 ## 预编译发布包（推荐）
 
 从 [GitHub Releases](https://github.com/zy445566/xbintsc/releases/latest) 下载对应
@@ -107,9 +113,10 @@ sudo apk add clang lld                   # Alpine
 用 `clang --version` 验证。如果 xbintsc 用错了链接器，可用 `xbintsc_CLANG` 指定
 clang，并通过 `xbintsc_LINKER_ARGS` 追加参数（例如 `-fuse-ld=lld`）。
 
-## Windows —— 安装 LLVM 与 MSVC C++ 生成工具
+## Windows —— 安装 MSVC C++ 生成工具（与 LLVM）
 
-用 `winget` 安装 LLVM 和 Visual Studio C++ 生成工具：
+Windows 上的 xbintsc 面向 **MSVC ABI**。用 `winget` 安装 Visual Studio C++
+生成工具和 LLVM：
 
 ```powershell
 winget install -e --id LLVM.LLVM
@@ -117,15 +124,22 @@ winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
   --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
 ```
 
-clang 需要 MSVC/SDK 的环境变量（`INCLUDE`、`LIB`、`PATH`）才能找到 C 标准库头文件、
-导入库和链接器。请在 **x64 Native Tools Command Prompt for VS 2022**（Windows on
-ARM 上用 **ARM64 Native Tools** 提示符）中运行 `xbintsc`，或自行导入环境：
+Visual Studio 2022 自带的 LLVM（`VC\Tools\Llvm\x64\bin\clang.exe`，当前版本
+19.1.5）已经够用，独立安装的 LLVM 也可以。但编译器必须以 MSVC ABI 为目标
+（`Target: *-windows-msvc`）：面向其他 Windows ABI 的 clang 无法与 MSVC
+运行库链接，`xbintsc` 会直接给出明确错误并拒绝使用。
+
+通常**不再需要**开发者命令提示符：`xbintsc` 会按绝对路径找到 Visual Studio
+自带的 LLVM，而这个 clang 会自行定位 MSVC/SDK 的头文件、库与链接器。如果你的
+安装仍需要显式导入环境，可在 **x64 Native Tools Command Prompt for VS 2022**
+（Windows on ARM 上用 **ARM64 Native Tools**）中构建，或手动导入：
 
 ```powershell
 & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
 ```
 
-用 `clang --version` 验证。（也可用 chocolatey：`choco install llvm`。）
+用 `xbintsc doctor`（或 `clang --version`）验证；输出会列出解析到的编译器、
+版本与目标。
 
 ## 从源码构建（仅贡献者需要）
 

package/doc/zh-CN/unimplemented/classes.md

@@ -0,0 +1,22 @@
+# 类与面向对象
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/classes.md)
+
+| 特性 | 现状 |
+| --- | --- |
+| `class` 声明 / 类表达式 | ✓ 已实现 |
+| 构造函数 `constructor` | ✓ |
+| 实例字段 / 属性声明 | ✓ |
+| 方法 | ✓ |
+| `static` 字段 / 方法 | ✓ |
+| 继承 `extends` / `super` | ✓（单级正确；`super` 取 `this` 原型的原型，理论缺陷见[运行时偏差](./deviations.md)） |
+| 原型链 / 方法查找 | ✓ |
+| `instanceof` | ✓ |
+| `new` / 实例化 | ✓ |
+| `get` / `set` 访问器 | ✓ 已实现 |
+| 参数属性 `constructor(public x: T)` | ✓ 已实现 |
+| 私有字段 `#x` | ✓ 已实现（以字面量 `#x` 作为键存储；无访问控制强制） |
+| `enum` / `const enum` | ✓ 已实现（正向 + 反向映射） |
+| `private` / `protected` / `public` / `readonly` 修饰符 | ✗ 无访问控制（擦除） |
+| `abstract` / `implements` | ✗（擦除） |
+| 父子类 `#x` 同名 | ✗ 可能混用（同一字面量键） |

package/doc/zh-CN/unimplemented/deviations.md

@@ -0,0 +1,24 @@
+# 运行时偏差
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/deviations.md)
+
+这些特性**能编译、能运行**，但结果不完全符合 ECMAScript：
+
+| 项 | 偏差 |
+| --- | --- |
+| 正则按字节匹配 | 引擎按 UTF-8 字节匹配：多字节字面量仍可匹配，但 `.` 与字符类每次只消费一个字节（`\d`/`\w` 仍是 ASCII）。`exec` / `search` / 替换回调返回的偏移会转换为 UTF-16 码元 |
+| 全局正则 `lastIndex` | `/g`、`/y` 正则的 `test` / `exec` 不推进也不读取调用方设置的 `lastIndex` |
+| `String.normalize` | 未实现 |
+| 内置方法一等公民 | 以未绑定方法值实现（见[函数](./functions.md)）；`fn.toString()` 返回占位字符串而非源码文本 |
+| `for...in` | 枚举对象 / 数组 / 字符串的自身键；不含原型链属性 |
+| 数组越界 / 稀疏 | 越界访问返回 `undefined`；对 `arr.length` 赋值会截断 / 扩展，但不区分稀疏空洞 |
+| 内存管理 | 非移动标记-清扫回收器（在 `xt_alloc` 之后）：显式根、子系统根提供者与保守 C 栈扫描。单线程、stop-the-world；无移动/压缩与分代 |
+| 函数 `arity` / 调用参数个数 | 无参数个数校验；`fn.length` 报告声明的 arity，但调用不做校验 |
+| `async` / `await` | 已在栈式协程上真实挂起；`await` 总会排入一次微任务（非 Promise 与已 settle 的 Promise 也一样），因此与 pending `.then` 回调的交错顺序符合规范。顶层 `await` 会阻塞事件循环等待，而不是让出模块主体。`fs/promises` 与 `fetch` 把阻塞工作 offload 到 4 线程池并在 reactor 上 settle。异步生成器可在 `await` 与 `yield` 处挂起，`for await...of` 每次迭代等待一步 |
+| 异步生成器清理 | `for await...of` 提前退出时不会调用迭代器的 `return()`。异步生成器中的 `yield*` 只委托同步可迭代对象。在挂起的 `yield` 处调用 `.return()` 会直接完成而不执行 `finally`（与同步生成器相同的限制） |
+| `super` | `super.x` / `super(...)` 取 `this` 原型的原型；单级继承正确，继承深度 > 1 时可能不准确 |
+| `Error.stack` | 仅函数级帧：每帧为 `at 名称 (文件:行)`，行号取自函数声明（最内层帧会更新为错误构造处）；没有列号，生成器 / `async` 函数体不产生帧（它们会切换栈） |
+| 模块实时绑定 | 命名空间导入与导入绑定为快照（见[模块系统](./modules.md)） |
+| `import.meta` | ✓ `import.meta.url` / `.dirname` / `.filename`，由可执行文件路径解析 |
+
+> 数字格式化、宽松相等、`+` / 关系运算 `ToPrimitive`、整链可选链、`finally` 提前退出、对象键顺序等均已对齐 Node，并由差分测试覆盖，故不再列为偏差。

package/doc/zh-CN/unimplemented/expressions.md

@@ -0,0 +1,24 @@
+# 表达式与运算符
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/expressions.md)
+
+## 解析但代码生成报 `UnsupportedFeature`
+
+无——生成器已实现。
+
+> 标记模板已实现，含 raw 字符串与 `String.raw`。生成器（`function*`、`yield`、`yield*`）
+> 基于有栈协程实现，支持 `next`/`throw`/`return`、`for...of`、展开与委托；
+> `async function*` 与 `for await...of` 已实现：函数体可在 `await` 与 `yield` 两处挂起，
+> 每次 `.next()` 返回 Promise。`import.meta` 提供 `url`、`dirname`、`filename`，
+> 由正在运行的可执行文件路径解析（见[模块系统](./modules.md)）。
+
+## 解析器不支持
+
+目前未知有表达式级别的缺口。
+
+## 运算符未实现
+
+| 运算符 | 现状 | 说明 |
+| --- | --- | --- |
+| `new.target` | ✗ | 已解析，但以 `UnsupportedFeature` 明确拒绝（无 `new.target` 语义） |
+| `typeof` / `void` / `in` / `delete` / `instanceof` | ✓ | 映射到运行时辅助函数（`xt_typeof`、`xt_in`、`xt_delete`、`xt_instance_of`） |

package/doc/zh-CN/unimplemented/functions.md

@@ -0,0 +1,21 @@
+# 函数
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/functions.md)
+
+| 特性 | 解析 | 语义 |
+| --- | --- | --- |
+| 默认参数 `function f(a = 5)` | ✓ | ✓ 已实现 |
+| 剩余参数 `function f(...args)` | ✓ | ✓ 已实现 |
+| 调用参数展开 `f(...args)` | ✓ | ✓ 已实现 |
+| 解构参数 / 解构绑定 | ✓ | ✓ 已实现 |
+| `arguments` 对象 | ✓（隐式） | ✓ 已实现（箭头函数取的是自身参数，而非外层函数的 `arguments`，与 JS 不同） |
+| `this` 绑定 / 方法调用语义 | ✓ | ✓ 已实现（`this` 作为函数首个 ABI 参数线程化；箭头函数词法继承） |
+| `async` / `await` / Promise | ✓ | ✓ 已实现：基于栈式协程的真实挂起；等待 pending promise 会暂停函数体并由事件循环恢复（剩余差异见偏差表） |
+| `new.target` | ✗ | 已解析，但以 `UnsupportedFeature` 明确拒绝（无 `new.target` 语义） |
+| 生成器 / 迭代器 / `yield` | ✓ 已实现 | `function*`、`yield`、`yield*`、`.next/.throw/.return`；`async function*`、`for await...of` 与 `Symbol.asyncIterator` 也已支持 |
+| 闭包 `arity` | — | `xt_closure_arity` 恒为 -1，未填充 |
+| `fn.call` / `fn.apply` / `fn.bind` | ✓ | ✓ 已实现（绑定闭包不跟踪部分参数的 `length`） |
+| `fn.name` / `fn.length` | ✓ | ✓ 已实现（从声明 / 赋值 / 属性键推断；绑定函数为 `"bound ..."` 并调整 arity） |
+| 内置方法一等公民（`typeof arr.map`、`const f = arr.push`、`obj.method?.()`） | ✓ | ✓ 作为**未绑定**方法值实现：读取 `arr.map` 得到函数，`arr.map?.(cb)` 与 `obj.method?.()` 会把接收者作为 `this` 绑定，脱离接收者调用（`const f = arr.map; f(cb)`）会像 JavaScript 一样抛错。方法的 `name`/`length` 也一并暴露 |
+| 内建构造器一等公民（`const A = Array`、`new A(...)`、`typeof Map`） | ✓ | ✓ 构造器是普通函数值，带 `name`/`length`、`prototype`、静态成员（`A.isArray`）与完整的 `instanceof` 协议 |
+| `fn.toString()` | ~ | 返回原生占位字符串（`function name() { [native code] }`），而非原始源码文本 |

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

@@ -0,0 +1,19 @@
+# 模块系统
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/modules.md)
+
+| 功能 | 现状 |
+| --- | --- |
+| 多文件 / 模块解析与链接 | ✓ 驱动层 AST 打包（`src/driver/modules.ts`）：解析每个模块、按模块前缀重命名顶层符号、改写引用后合并为单文件重新绑定 |
+| 具名导入导出 | ✓ `import { a, b as c }` / `export { a as b }` / `export const/let/var/function/class` |
+| 默认导入导出 | ✓ `export default` / `import d from` |
+| 再导出 `export { x } from` / `export * from` | ✓（`export *` 复制依赖模块的导出） |
+| 命名空间导入 `import * as ns` | ✓ 降级为持有全部导出的合成对象字面量 |
+| 循环依赖 | ✗ 直接报错（不做循环初始化语义） |
+| 实时绑定（live bindings） | ✗ 命名空间对象与导入绑定是模块求值时的快照 |
+| ESM `node_modules` 包 | ✓ 裸说明符沿目录树解析，支持 `exports` / `module` / `main`、作用域包与子路径；包源码与相对模块一样被打包 |
+| CommonJS `require` / `module.exports` | ✓ 仅限 `node_modules` 内：打包器为每个 CommonJS 包注入合成的 `module` / `exports`，将 `require("x")` 降级为依赖的导出对象，并把外部/内置 `require` 提升为 ESM `import`。用户代码（`node_modules` 之外）的 `require()` 仍会报错并提示改用 ESM `import` |
+
+> 扩展模块（如 `fs`）可通过裸名称或 `node:` 前缀的 `import` 引入 —— `import { readFileSync } from "fs"` / `import path from "path"` —— 并解析到运行时入口（具名、默认与命名空间形式均可）。相对模块与 `node_modules` 中的 ESM/CJS 包均在驱动层打包。
+
+这份契约的已实现部分见[模块系统](../implemented/modules.md)。

package/doc/zh-CN/unimplemented/node/async.md

@@ -0,0 +1,20 @@
+# 异步与事件循环模型
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/async.md)
+
+已实现部分：
+
+- 核心事件循环 `runtime/xt_loop.c`（`select(2)` 反应堆），`net` / `dgram` / `http` 均构建于其上。
+- 异步 I/O offload `runtime/xt_async_io.c`：阻塞的文件与 HTTP 客户端工作在 4 个工作线程上执行，并在 reactor 上完成，因此 `fs/promises` 与 `fetch` 不会卡住定时器或套接字。
+- `Promise`、`async` / `await` 已可用（见核心文档），`fs/promises` 返回从 reactor settle 的 Promise。
+- 定时器已作为全局函数提供：`setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` 运行在核心反应堆上，并在仍有定时器时保持进程存活。
+- 提供独立的 `EventEmitter`（`events` 模块，同时也是全局构造函数）；流与套接字额外具备内部发射器方法（`on` / `addListener` / `once` / `off` / `removeListener` / `emit`）。
+
+仍未实现：
+
+- Node 的 `Timeout` 对象（`setTimeout` 返回数字 id；`setImmediate` 与 `queueMicrotask` 已作为全局函数提供）。
+- 文件监听：`fs.watch` / `fs/promises.watch` 返回惰性对象；没有 inotify/kqueue/ReadDirectoryChangesW 后端。
+- `Dir.read` / `Dir.close` 立即调用回调，回调式 `fs.readFile` / `fs.writeFile` / … 仍不支持（请用 `fs/promises` 或 `*Sync` 形式）。
+- 流与套接字的内置 `once` 等同 `on`（不具「触发一次后移除」语义）；`events` 模块的 `EventEmitter` 实现了真正的 `once`。
+- `net` 的 `connect` 仍是在套接字加入 reactor 之前执行的阻塞 `connect(2)`；HTTP 响应要求 `Connection: close`，不做 keep-alive / 分块传输 / 流水线复用。`fetch` 没有 TLS，且在 resolve 前缓冲整个响应体。
+- offload 线程池固定为 4 个 worker；没有线程池大小选项，也不支持对排队 job 的 `AbortSignal` 取消。

package/doc/zh-CN/unimplemented/node/bun.md

@@ -0,0 +1,8 @@
+# Bun 扩展
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/bun.md)
+
+设计文档中提到的 `Bun.file` 等 Bun API 仅作为扩展机制的设计示例，**尚未实现**：
+
+- 无 `bun` 扩展目录、无 Bun 内置函数、无 Bun C 运行时。
+- `src/extensions/` 下目前只有 `node` 一个平台扩展（外加核心扩展）。

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

@@ -0,0 +1,12 @@
+# `fs/promises` 模块的缺口
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/fs-promises.md)
+
+`fs/promises` 现在把阻塞 I/O offload 到异步 I/O 线程池（已实现表面见[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）；剩余差异主要是行为层面的：
+
+- `FileHandle.appendFile` 行为等同 `writeFile`（按当前文件位置写入，而不是追加）。
+- `FileHandle.readFile()` 从当前描述符偏移读取。
+- `Dir.read` / `Dir.close`（同步与 Promise 形式）立即调用回调；`Dir.readSync` / `closeSync` 仍是同步的。
+- `watch` resolve 为与 `fs.watch` 相同的、永不触发的 watcher；没有真正的文件监听后端。
+- 读写是一次性整体操作；没有流式 `FileHandle` 变体，也不支持 `AbortSignal` 取消。
+- 线程池固定为 4 个 worker；大量并发操作会排队（但仍不会阻塞事件循环）。

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

@@ -0,0 +1,24 @@
+# `fs` 模块
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/fs.md)
+
+`fs` 实现了**同步** API 表面（文件、目录、描述符、元数据、链接、`cp`、`glob`、`Dir`、`constants`），`fs/promises` 则把每个文件/描述符操作跑在异步 I/O 线程池上（见[已实现：`fs`](../../implemented/node/fs.md)与[已实现：`fs/promises`](../../implemented/node/fs-promises.md)）。仍缺少的主要是需要不同后端或回调管线的 API：
+
+| 未实现 API | 类别 |
+| --- | --- |
+| `readFile` / `writeFile` / `appendFile` / `open` / `close` / `read` / `write` / `stat` / … | 回调式异步文件操作（`fs/promises` 提供 Promise 形式） |
+| `createReadStream` / `createWriteStream` | 流式读写 |
+| `watch` / `watchFile` | **真正的**文件监听：函数存在但返回对象从不触发（无 inotify/kqueue 后端） |
+| `openAsBlob`、`statfs` 回调形式、`rmdir` 的 `maxRetries` / `retryDelay` | 需异步重试的杂项选项 |
+| `glob` 的 `exclude` / `follow`、`cp` 的 `filter` | 选项回调 |
+
+## 读取语义缺口
+
+- `readFileSync` 支持编码选项（默认/`utf8`/`ascii`/`latin1`/`binary`/`hex`/`base64`/`base64url`），但默认**不返回 `Buffer`**：即使提供了 `Buffer`（以普通对象模拟），`readFileSync` 仍以字符串返回。要读取原始字节请显式指定。
+- 未实现 `utf16le` / `ucs2` 解码（按文本返回字节）。
+- `watch` / `watchFile` / `unwatchFile` 返回 API 形态的发射器对象，`.close()` / `.on()` 方法存在但**不会触发**事件。
+- `Dir.read(cb)` / `Dir.close(cb)` 会**同步**完成（回调立即被调用）；`FileHandle` 方法现在返回真正的 Promise。
+- `mkdtempSync` 总是向前缀追加 6 个随机字符（不要求以 `XXXXXX` 结尾）。
+- `globSync` 支持 `*`、`?`、`[...]`、`**`，但不支持 `exclude` 回调与 `follow`；`**` 不跟随符号链接（与 Node 默认一致）。
+- `cpSync` 的符号链接处理在常见场景下与 Node 一致，但不支持 `verbatimSymlinks`。
+- 平台差异：Windows 上 `readlinkSync` 抛 `ENOSYS`，`chmodSync` / `lchmodSync` / `chownSync` / `lchownSync` / `fchmodSync` / `fchownSync` 为空操作；`statfsSync` 在 Windows/AIX/Sun 返回全零字段；`lutimesSync` 在 macOS/Windows 退化为 `utimesSync`。

package/doc/zh-CN/unimplemented/node/globals.md

@@ -0,0 +1,14 @@
+# 全局对象与命名空间
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/globals.md)
+
+| 未实现 | 说明 |
+| --- | --- |
+| `global` / `globalThis` | 无 |
+| `__dirname` / `__filename` | 无 |
+| `require` / `module` / `exports` | 仅限 `node_modules` 内的包（打包器会降级）；用户代码需使用 ESM `import` |
+| 未 `import` 的 `fs.readFileSync(...)` | ✗ 不支持。`fs` 不是全局对象；请先导入（`import fs from "fs"` 或 `import * as fs from "node:fs"`），之后 `fs.readFileSync(...)` 会下降为该模块的运行时符号。 |
+
+Node 模块通过裸名称或 `node:` 前缀的 `import` 引入（`import { readFileSync } from "fs"`、`import path from "path"`、`import { platform } from "node:os"`）。具名与命名空间导入都会解析到扩展模块的运行时入口。
+
+已支持的命名空间调用：`path.*`、`os.*`、`process.*`、`fs.*`、`fs/promises.*`（方法）、`child_process.*`、`crypto.*`、`url.*`（需先导入；`path`/`os`/`process` 也可使用全局名），以及基于分发器的 `Buffer.*`、`stream.*`、`net.*`、`dgram.*`、`http.*` 和 `process.platform` / `process.argv` 等属性。`Readable` / `Writable` / `Duplex` / `Transform` / `PassThrough` / `Buffer` 亦可用作全局构造函数。

package/doc/zh-CN/unimplemented/node/modules.md

@@ -0,0 +1,15 @@
+# 完全未实现的模块
+
+> 属于[Node 扩展：未实现](../node.md) · [English](../../../unimplemented/node/modules.md)
+
+以下 Node 内置模块没有任何对应扩展 / 内置函数（`fs` / `fs/promises` / `path` / `os` / `process` / `buffer` / `stream` / `dgram` / `http` / `events` / `util` / `querystring` / `assert` / `test` 已实现，`crypto` / `url` / `child_process` / `zlib` / `stream/promises` / `worker_threads` 部分实现，见[已实现：Node 扩展](../../implemented/node.md)）：
+
+| 模块 | 说明 |
+| --- | --- |
+| `https` | TLS 版 HTTP |
+| `readline` | 命令行读取 |
+| `tls` / `cluster` / `vm` | 其余未列出的核心模块 |
+
+> `crypto`（仅 `createHash`，现支持流式 API）、`url`（仅 `pathToFileURL` / `fileURLToPath`）、
+> `child_process`（仅 `spawnSync`）、`zlib`（仅 `createGzip`）与
+> `worker_threads`（仅 `Worker` / `isMainThread` / `workerData` / `parentPort`）目前为部分实现。

package/doc/zh-CN/unimplemented/node.md

@@ -0,0 +1,18 @@
+# Node 扩展：未实现
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/node.md)
+
+Node 扩展实现了 21 个模块以及事件循环集成；已实现表面按模块记录在
+[Node 扩展：已实现](../implemented/node.md)。本节记录缺失或与 Node 不同之处。
+
+## 目录
+
+- [`fs`](./node/fs.md) —— 回调式异步操作、真正的文件监听、选项回调
+- [`fs/promises`](./node/fs-promises.md) —— `FileHandle` 追加/读取偏移、`Dir` 回调立即完成、`watch` 不触发、无取消
+- [完全未实现的模块](./node/modules.md) —— `https`、`readline`、`tls`、`cluster`、`vm` 等
+- [全局对象与命名空间](./node/globals.md) —— `global`、`__dirname`、`node_modules` 之外的 `require`
+- [异步与事件循环模型](./node/async.md) —— 文件监听缺失、阻塞式 `net.connect`、无 keep-alive、固定大小线程池
+- [Bun 扩展](./node/bun.md) —— 仅为设计示例
+
+模块的已实现页面会链接到对应限制页；限制解除后，把条目移到
+`../implemented/node/` 下对应页面。

package/doc/zh-CN/unimplemented/statements.md

@@ -0,0 +1,15 @@
+# 语句
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/statements.md)
+
+## 解析但代码生成报 `UnsupportedFeature`
+
+| 语法 | 现状 | 说明 |
+| --- | --- | --- |
+| `namespace` / `module` 声明 | 解析 ✓，代码生成 ✗ | → "does not yet support this statement (module declaration)" |
+
+> 标签语句（`label: statement`、`break label`、`continue label`）已实现，包括非循环语句上的标签。
+
+## 解析器不支持（直接语法错误）
+
+目前未知有语句级别的缺口。解析器有意保持宽松，接受绝大多数 TypeScript 语句语法；不支持的形式会在代码生成阶段报错（见上）。

package/doc/zh-CN/unimplemented/stdlib.md

@@ -0,0 +1,54 @@
+# 标准库
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/stdlib.md)
+
+## 已实现（概要）
+
+- 数组：`push` `pop` `shift` `unshift` `join` `slice` `splice` `indexOf` `lastIndexOf` `includes` `concat` `reverse` `forEach` `map` `filter` `reduce` `reduceRight` `find` `findIndex` `findLast` `findLastIndex` `some` `every` `sort` `flat` `flatMap` `fill` `copyWithin` `at` `keys` `values` `entries`，以及不可变的 `toReversed` / `toSorted` / `toSpliced` / `with`
+- 字符串：`charAt` `charCodeAt` `codePointAt` `indexOf` `lastIndexOf` `includes` `startsWith` `endsWith` `slice` `substring` `substr` `split` `match` `replace` `replaceAll` `search` `toUpperCase` `toLowerCase` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `concat` `at` `localeCompare` `valueOf`
+- `Math`：完整函数与常量
+- `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`，对象展开 `{...obj}`
+- 全局函数：`parseInt` `parseFloat` `isNaN` `isFinite` `Number` `String` `Boolean` `encodeURI` `decodeURI` `encodeURIComponent` `decodeURIComponent`
+- `console.log` / `info` / `warn` / `error` / `dir` / `trace` / `assert` / `count` / `group` / `table` / `time`
+
+## 已补齐
+
+- `JSON.parse` / `JSON.stringify`
+- `Date`、`RegExp`（POSIX ERE 子集，支持捕获组）、`Map`、`Set`、`Promise`、`BigInt`
+- `Array` 静态（`isArray/of/from`）、`Object` 静态、`Number` 静态、`String` 静态（`fromCharCode` / `fromCodePoint` / `raw`）
+- 一等公民内建构造器（`const A = Array`、`new A(...)`、`A.isArray`、`x instanceof A`）与 `Object.prototype`（`hasOwnProperty`、`toString`、`valueOf`、`isPrototypeOf`、`propertyIsEnumerable`、`__proto__`），且 `Object.getPrototypeOf({}) === Object.prototype`
+- `Error` 家族（`Error`、`TypeError`、`RangeError`、`SyntaxError`、`ReferenceError`、`EvalError`、`URIError`、`AggregateError`）：支持 `new`、`instanceof`、`extends`、`String(err)` / `err.toString()` 与 `.stack`
+
+## 仍未实现
+
+| 类别 | 现状 |
+| --- | --- |
+| `Symbol` 构造器与 symbol 原始值 | ✓ `Symbol(description)`、著名符号、`Symbol.for` / `Symbol.keyFor`、symbol 属性键与 `Object.getOwnPropertySymbols` |
+| `String.prototype.normalize` | ✗ 未实现 |
+| `structuredClone` | ✓ 数组、对象、Map、Set、Date、RegExp 与类型化数组（保留循环引用与共享引用）；函数、symbol、Promise、生成器会被拒绝 |
+| `JSON.stringify` 选项 | ✓ 支持 `space`（数字或字符串，最多 10 个单位）、函数/数组 `replacer` 与 `toJSON` |
+| 内置错误子类（`TypeError`、`RangeError` 等） | ✓ 一等公民构造器与原型；整个家族 `instanceof Error` 成立 |
+| `AggregateError` 构造器 | ✓ `new AggregateError(errors, message)`；`Promise.any` 现以其作为 rejection |
+| 迭代器协议 / `Symbol.iterator` / `for...of` 自定义可迭代 | ✓ 数组、字符串、`Map`、`Set`、生成器以及任何暴露 `[Symbol.iterator]()` 的对象均可在 `for...of` / 展开中使用 |
+| 生成器（`function*`、`yield`、`yield*`、`next`/`throw`/`return`） | ✓ 基于有栈协程实现；支持 `for...of`、展开与委托；`async function*`、`for await...of` 与 `Symbol.asyncIterator` 也已支持 |
+| 定时器与微任务 | ✓ 核心事件循环提供 `setTimeout` / `clearTimeout` / `setInterval` / `clearInterval` / `setImmediate` / `clearImmediate` / `queueMicrotask` 与 `performance.now`（返回数字 id，无 `Timeout` / `Immediate` 对象）。定时器 settle 的 promise 可以被 await：async 函数体在 pending promise 上挂起，定时器触发时恢复 |
+| I/O / 进程等宿主 API | 仅通过扩展（如 Node `fs`）提供 |
+
+## 类型化数组
+
+已实现：`Uint8Array`、`Int8Array`、`Uint8ClampedArray`、`Uint16Array`、
+`Int16Array`、`Uint32Array`、`Int32Array`、`Float32Array`、`Float64Array`，支持
+`new X(n)` / `new X(数组样)`、`X.from` / `X.of`、`BYTES_PER_ELEMENT`、按类型强制的
+元素写入，以及 `fill` / `set` / `slice` / `subarray` / `join` / `toString` /
+`indexOf` / `lastIndexOf` / `includes` / `forEach` / `map` / `filter` / `every` /
+`some` / `find` / `findIndex` / `reduce` / `reverse` / `sort` / `copyWithin` /
+`at` / `keys` / `values` / `entries`。已知差异：
+
+| 功能 | 现状 |
+| --- | --- |
+| `subarray` | ✓ 返回共享同一缓冲区的视图；`slice` 复制 |
+| `keys` / `values` / `entries` | ~ 返回数组，而非迭代器对象 |
+| `ArrayBuffer` / `DataView` / `.buffer` / `.byteOffset` 语义 | ✓ `ArrayBuffer`（`slice`、`isView`）、`DataView`（默认大端，可选 `littleEndian`）、类型化数组由缓冲区支撑并暴露 `.buffer` / `.byteOffset`；`new X(buffer, offset, length)` 创建视图 |
+| `BigInt64Array` / `BigUint64Array` | ✗ 未实现 |
+| `instanceof` 内建构造器 | ✓ `instanceof Array` / `Object` / `Map` / `Set` / `Date` / `RegExp` / `Promise` / `Error` 家族 / 类型化数组都能按名字识别，**也能通过一等公民构造器值判断**（`const A = Array; x instanceof A`）；构造器可保存、传参、取别名、调用与 `new` |
+| 基于 `Buffer` / `ArrayBuffer` 的类型化数组视图 | ✓ 类型化数组与 `DataView` 共享 `ArrayBuffer` 字节；基于 `Buffer` 的视图仍未实现 |

package/doc/zh-CN/unimplemented/toolchain.md

@@ -0,0 +1,14 @@
+# 工具链、平台与工程
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/toolchain.md)
+
+| 项 | 现状 |
+| --- | --- |
+| GC（垃圾回收） | ✓ `xt_alloc.c` 中的非移动标记-清扫，按存活堆阈值（`XT_GC_THRESHOLD` 可固定该阈值）或 `xt_gc_collect()` 触发；每次回收后阈值变为存活堆的 2 倍（下限 1 MiB），因此常驻内存跟随存活集而不是只增不减；`XT_GC_TRACE=1` 会为每次回收向 stderr 打印一行统计。显式根 + 根提供者 + 保守活动栈扫描。`WeakMap`/`WeakSet` 的键是 ephemeron（只有键可达时才保留值），`WeakRef` 目标不可达时会被清空；由于栈扫描是保守的，残留的栈字可能延迟清空。无压缩或后台回收 |
+| 自举（self-hosting） | ✓ 编译器已能自编译：`xbintsc build src/cli/main.ts` 可产出可用二进制，且从第 1 代起产出的 IR 保持稳定。运行时仍为 C |
+| 类型检查器 | ✗ 仅定义诊断码，无 checker |
+| 完整标准库 | 部分：Math / JSON / Date / Map / Set / RegExp / `Error` / `BigInt` / `Symbol` / `structuredClone` 已实现；String.normalize 缺失 |
+| 多文件模块打包 | 部分：相对路径 `.ts` 打包、ESM `node_modules` 包、命名空间导入、裸说明符扩展模块导入已实现；CommonJS 仅在 `node_modules` 内处理；循环依赖 / 实时绑定未实现 |
+| 异步运行时 | ✓ `async`/`await` 在 `select(2)` reactor 上对 pending promise 挂起：定时器、TCP 套接字、offload 的文件/HTTP 工作与 promise 回调都能恢复协程。仍缺：真正的 OS 级文件监听、非阻塞 `net.connect`、`fetch` 的 TLS，以及用户可见的 worker 线程（`worker_threads` 仍用子进程） |
+| Windows 二进制产物验证 | 构建层已适配（`.exe` 后缀、链接参数分支），并在 CI 中验证 |
+| 精确的 ECMAScript 数值 / 字符串 / 比较语义 | 部分，见[运行时偏差](./deviations.md) |

package/doc/zh-CN/unimplemented/types.md

@@ -0,0 +1,11 @@
+# 类型系统
+
+> 属于[未实现语法与功能](../unimplemented.md) · [English](../../unimplemented/types.md)
+
+类型语法被解析为 AST 后在绑定 / 代码生成阶段**整体擦除**，不做任何类型检查：
+
+- 类型注解、返回类型、类型参数、类型别名、接口、泛型约束等：解析 ✓，检查 ✗。
+- 检查器诊断码（`TypeMismatch` `NotCallable` `PropertyNotFound` `ArgumentCountMismatch`）已定义但**未使用**。
+- `as` / `satisfies` / 非空断言 `!`：直接擦除，不做任何断言语义。
+- 泛型：无运行时实例化，类型参数被忽略。
+- 可选链 `?.` 的类型窄化：无（运行时短路已实现，但无类型层面的窄化）。