docs/ROADMAP.md · 施探宇/VML

# VML 路线图

> **版本**: v1.66.123 | **更新**: 2026-09-20 | 编译约束强化 R1–R10 立项（分层优先级规则入档）+ 编译错误退出码修复 + R1 变量检查(C) + R4 多诊断 + R7 行列号 + R8 缺库报错 + R9 错误不产 VML + R10 测试防卡死 + R6 syscall 9 处防护 + **R5 裸名 .linked 语言感知解析（第三类 static 泄漏 95→0）** + **语言专用库门禁与 naming 规范 builtin_&lt;lang&gt;／library_&lt;lang&gt;** + 全量 **1592 通过 / 8 跳过**（共 1600，0 失败）+ **64 位补缺指令 6 条** + 共享库逐函数测试 12/12 + GenDev 23/23
>
> ⚠ 本行的版本号由 `Scripts/sync_version.sh` 从 `VERSION` 同步；**改版本号时请一并改这一行的描述**，
> 否则会出现「版本写着 v1.66.89、描述停在 v1.66.85」这种自相矛盾（v1.66.89 时发生过一次）。
>
> （旧路线图归档件已于 2026-10-05 删除，需要时见 git 历史。）

---

## 当前状态

22 种语言前端全部完成 (🟢 22 种生产可用)，BASIC 支持7种方言 (--basictype)。18 翻译器中 17/18 ≥95%，MSP430/PIC24 16位无硬件浮点。

## 近期目标 (v1.67.x)

### 编译约束强化 (R1–R9) — 2026-09-20 立项

> 目标：把「静默接受错误代码」改成「必须报错 / 报警告」，并让一次编译能报出多条诊断。
> 下列各条的「现状」均为 2026-09-20 实测（逐语言编译 + 逐份比对生成产物），**目前基本都未实现**。

> **分层优先级规则（用户 2026-09-20 定，统领本节全部改动）**
>
> ```
> VML 语言定义 > VML 编译器 > C 编译器 > 共享库 > 其他语言编译器 > 其他语言库 > 例程源码
> ```
> **改了优先级高的，优先级低的一律要跟着适配改动**——必须主动回头扫一遍并改到位。
> 遇到「上层严格、下层报错」的冲突**永远改下层**（改库、改例程），不许放宽上层检查。
> 当天实例：C 编译器（第 3 级）加「未声明变量必须报错」后，共享库（第 4 级）立刻曝出
> `dos.c` / `string.c` 两处未声明调用——修的是库，不是放宽编译器。

- [ ] **R1 静态语言：未声明的变量和函数必须报错**
  范围：C / C++ / ObjC / D / Java / C# / Swift / Kotlin / Dart / Go / Rust / Pascal / Fortran / Ladder
  - 现状 —— 读未声明变量 **12/13 静默接受**：C++/ObjC/D/Java/C#/Swift/Fortran/Pascal/Dart 凭空造出全局
    `var_zzz: .word 0`；ObjC/D/Dart/Fortran 在赋值路径改造成栈上局部；Kotlin **整项丢弃**
    （`a + zzz` 编译成 `a`）；Go/Rust 发悬空符号引用，只在链接期报「未解析的数据引用」。
  - 现状 —— C 的读取路径**假定为 0 继续**（`CCompiler/CodeGenerator.Expressions.cs:168`），
    且那句警告被 `DebugMode` 门控，非 `-g` 时连警告都没有；赋值路径会报错且不产出产物。
  - 现状 —— 调用未声明函数 **9/9 静默**（C 仅「警告 + 推迟到链接期」，`CCompiler/Parser.Expressions.cs:792`）。
  - [x] C：读取路径「假定为 0」改为报错
  - [x] C：未声明函数调用改为报错（删除 `Parser.Expressions.cs` 那句对**每个**具名调用
        无条件打印的「可能未声明」提示；真正的检查放在代码生成阶段：
        名字不在 `ast.Functions`（含原型）且不是变量时记 `CodeGen_UndefinedFunction`）
  - [x] **实测抓到 2 处库源码 bug**（R1 上线后重建共享库暴露，已按标准修库）：
        `Lib/shared/src/dos.c` 使用未声明的 `_vml_result_int`（`graphics.c` 有声明，它没有，
        此前被「假定为 0」兜着 —— `GetDate`/`GetTime` 一直读到 0）；
        `Lib/shared/src/string.c` 调用未声明的 `vml_alloc`（`realloc.c` 声明了，它没有）
  - [x] **★ 链接器缺陷：C 程序会链入整套 BASIC 库**（2026-09-20 查实并**已于 v1.66.94 修复**）
    - **最终修法不是下面设想的"调换 1a/1b"**：那条路当时实测会破坏 printf 的 `%d`/`%s` 输出而被放弃。
      真正落地的是**语言感知解析** —— 裸名按 `Lib/<当前语言>/ → Lib/shared/` 的固定顺序解析，
      由 `LinkLibraries(languageDir)` 接入 10 个调用点（见本节下方的实施记录）。
      回头看不难理解为什么调换顺序没用：**"谁先被扫到"根本不构成正确答案**，
      正确答案是"当前语言的那一份"，而这一点当时两条路都没表达出来。
    - 回归（按本条原先的要求逐项补齐）：`Lang_C` **132 项全过 / 0 失败**（旧文写的 218 项是当时的口径）；
      全量 **1600 项 / 1592 通过 / 0 失败 / 8 跳过**；C 程序端到端实跑输出 `42`
      （旧文点名的 `smoke.c` 是当时调查用的临时文件，现已不存在，以等价证据替代）。
    - 下面保留当时的排查记录（含已排除的 4 个假设与插桩证据），作为这段弯路的历史。
    - 现象：编译一个 C 程序，`--dump-link` 显示链入了 `Lib/basic/` 的**全部**模块
      （builtins/crt/console/convert/string/math/ctype/…）。66 个模块里有一大半是 BASIC 的。
    - 根因：`VMLAssembler/LibraryLinker.ResolveLinkedFile` 对**裸文件名**的解析顺序反了 ——
      `1a` 先查**全局文件索引**（按文件名，全 Lib 树扫描后缓存），`1b` 才回退到
      **参照文件自身目录**。而 `builtins.vml` / `console.vml` / `string.vml` 这类名字在
      **22 个语言目录里各有一份**，全局索引只留"先扫到的那个"（字母序在前的 basic），
      于是参照文件所在的 `Lib/c/` 根本不被查询。
    - 验证（A/B 对照，A=原顺序 / B=调换后）：
      | 指标 | A（现状） | B（调换后） |
      |---|---|---|
      | 链入 `Lib/basic` | 整套 | **0** |
      | 未解析的跳转/调用目标 | **31** | **0** |
      | 链入模块数 | 66 | 55 |
      | `smoke.c` 运行输出 | `smoke hello 42 len=5` ✅ | `smoke hello ` ❌ |
    - **为什么没有直接改**：B 消除了全部悬空调用（这正是 R1 函数检查的前置条件），
      但**破坏了 printf 的 `%d`/`%s` 输出**。再查一层：两版链入的**共享库实现基本相同**
      （唯一差异是少 `Lib/shared/readline.vml`），说明 B 并非"缺模块"，而是
      **此前误链的 BASIC 模块在替 C 兜底**——提供了另一份可用的实现，掩盖了 C 这条链自身的缺陷。
      典型的「两个缺陷互相掩盖」。
    - **2026-09-20 已排除的假设**（下次别再走这些弯路，最小复现是 `printf("%d\n", 42)`：
      对照版输出 `42`，修复版**什么都不输出**）：
      1. ~~标签冲突~~ —— 修复版产物里**没有任何重复的裸标签定义**（链接器做了去重）
      2. ~~printf / vsnprintf 实现不同~~ —— 两者函数体在两版里**逐字节相同**（54 行 / 15 行）
      3. ~~缺符号~~ —— 修复版的转换类符号反而**更多**（112 个 vs 对照版 72 个），
         只是少了 `BASIC_*` 那批；`int_to_str` / `itoa` / `vsnprintf` 两版都有裸名定义
      4. ~~缺模块~~ —— 模块集差异只差 `Lib/shared/readline.vml`，而它只定义 `read_line`，与 printf 无关
      → 剩下的方向：差异在**更深一层的调用目标解析**上。建议下次**直接插桩**
      `LibraryLinker` 的 `globalLabelMapping`，把这三种配置下的映射表 dump 出来 diff，
      比在 .vml 文本里逐层提取函数体有效得多（该文件里编译器内部标签 `L*/sta_*/_L*` 也顶格书写，
      按"下一个顶格标签"切函数体会被反复截断，我在这上面浪费了大量时间）。
    - [x] ~~修复路径（两步，必须一起做，顺序不能反）~~ —— **该路径已废弃，实际采用语言感知解析（见上方 [x] 说明）**：
      1. 调换 `ResolveLinkedFile` 的 1a/1b（自身目录优先，全局索引退为跨目录引用的兜底）
      2. **随即适配下层**（优先级的第 4/6 级）：补全 C 的包装链，
         让 `Lib/c/*` 自行提供 printf 格式化所需的全部依赖 —— 不许靠 BASIC 兜底
    - [x] ~~修好后回归：`Lang_C` 218 项、全量 1600 项、`smoke.c` 输出三项都要对~~ —— **已全部通过，结果见上方 [x] 条目**

- [ ] **C 的函数检查挪到链接期**（半成品，见下）：代码生成期判定「不在 `ast.Functions` 即未声明」
        是**错的** —— 本项目标准库自动链接，`printf` / `long_to_str` 这类由库提供的函数不在 AST 里，
        实测误伤 **74 个用例（10 种语言）**。正确位置是链接期的未解析符号检查
        （`VMLAssembler/LibraryLinker.ReportUnresolved`），那里才知道库究竟提供了什么。
        变量检查**保留**在代码生成期：全局变量不会被自动链接提供，未声明即未定义。
  - [ ] 顺带查实：`Lib/c/stdio.h:9`（`Lib/d/stdio.h`、`Lib/objc/stdio.h` 同）声明
        `#param lib("stdio_funcs")`，而 `stdio_funcs.vml` 早已作为过期文件删除
        （CHANGELOG:2656），引用从未清理 —— 所有含 `<stdio.h>` 的程序都在要求链接不存在的文件。
  - [ ] **静默产出空程序**（同属「静默接受」类）：不在仓库根目录运行 VMLTool 时，
        `.linked` 相对 basePath 解析不到 `Lib/`，整条链静默失败 —— 编译「成功」、退出码 0，
        产出 35 条指令的空壳，运行时才崩 `未找到标签: strcpy`。应报错而非静默通过。
        判据：正常产物上万条指令（全链接 blob ≈ 37745 条），几十条即为异常。
  - [ ] 其余 12 种静态语言接入统一机制

- [ ] **R2 动态语言：未初始化的变量禁止引用**
  - 范围：Python / JavaScript / Lua / Ruby / R / Scheme。现状 **6/6 静默接受**。
  - 判定策略：**确定赋值分析**（同 C# CS0165）—— 所有路径都未赋值 → 报错；某条路径可能未赋值 → 警告。
    这样不会误报 `while` 循环里「先用后赋值」这类写法。
  - **Lua 例外**：读未声明的全局变量返回 `nil` 是 Lua 语言设计（`if config == nil` 是惯用法），
    保持标准语义，不报错。

- [ ] **R3 未使用的局部变量与函数报警告**
  局部变量，以及外部无法访问的函数（`static` / 私有 / 内部），声明后未被使用 → 警告。

- [ ] **R4 一次编译允许报多个错误和多个警告**
  - 现状：`CompilerBase/DiagnosticBag.cs` 收集器已实现，C 的 lexer/parser 也已接入，
    但 `CCompiler/CCompiler.cs:109` 成功路径**直接 `return prog`，从不检查 `diagnostics`** ——
    只要解析没抛异常，收集到的错误就整包丢弃。这是「报不出多条」的根因。
  - [x] `CodeGeneratorBase` 补代码生成阶段的诊断入口（`Diagnostics` + `ReportError/ReportWarning` 过载）
  - [x] 成功路径检查诊断，错误与警告分别处理：`CCompiler.CompileFile` 此前**根本没有收集器**
        （首个错误直接抛），`Compile` 的成功路径**从不检查 diagnostics**（收集到的错误整包丢弃）
  - [x] CLI 汇总输出错误数与警告数（`DiagnosticBag.FormatAll` 尾部 `N error(s)/warning(s) generated.`）
  - [x] 顺带修构建脚本的同类缺陷：`gen_all_vml.sh` 执行子脚本不检查返回码，
        2 个模块编译失败仍打印「编译完成」且整个脚本 exit 0；`Lib/build_libs.sh`
        有 `FAILED` 计数却从不用它退出 —— 现均改为失败即非零退出

- [ ] **R5 库函数去重：同样功能只保留一个，优先共享库** ★ **已查实：这就是上面那个链接器缺陷的本质**
  - **2026-09-20 插桩 `globalLabelMapping` 得到的决定性证据**：同一个裸名在两个配置下
    解析到**不同模块的实现**，而差异只取决于**链接顺序**：

| 裸名 | 对照配置 | 调换解析顺序后 | first-wins 后 |
    |---|---|---|---|
    | `print_int` | `lib_io_print_int` ✅ | `lib_console_print_int` ❌ | `lib_builtins_print_int` ❌ |
    | `print_str` | `lib_io_print_str` ✅ | `lib_console_print_str` ❌ | `lib_builtins_print_str` ❌ |
    | `putchar` | `lib_io_putchar` ✅ | `lib_console_putchar` ❌ | `lib_io_putchar` ✅ |

- 机制：`LibraryLinker.cs:384` 合并映射时是 **last-wins**（直接赋值），后链接的模块
    **覆盖**先前的。而 `print_int` / `print_str` / `putchar` / `newline` 这类名字
    **在多个模块里都有定义**（`io.vml`、`builtins.vml`、`console.vml`…）——
    顺序一变，赢家就变。
  - **试过两种"顺序类"修法，都不成立**：调换 `ResolveLinkedFile` 的 1a/1b 与把映射合并
    改成 first-wins，都只是换了个赢家（`console` / `builtins`），没有一个能给出
    `io`。**这不是顺序问题，是"同一个功能有多份实现"的问题** —— 正是 R5。
  - ⚠ **一处未证实的推断（勿当结论）**：我曾推测"包装把裸名映射到自己 → `CALL print_int`
    自引用循环"，**这没有验证过，且与事实不符** —— 核对后 `lib_console_print_int` 只能来自
    `Lib/shared/console.vml`，而它和 `io.vml` 的 `print_int` **逐字节相同、都是真实现**，
    不存在自引用。**printf 失效的真正原因仍未查清**，别沿着这个推断往下走。
  - **R5 实测盘点（2026-09-20）**：`Lib/shared/` 内 **1488 个唯一名字、1583 处定义 → 95 个重复**。
    重复分三类，**处置方式完全不同**：

| 类别 | 例子 | 处置 |
    |---|---|---|
    | **真重复**（同类功能多份实现） | `print_int`/`print_str`/`println_int`（builtins, console, io **三份逐字节相同**）、`wcscat`/`wcslen`（wchar, wstring） | 保留一份，优先共享库（`io`） |
    | **同名不同义**（命名冲突，非重复） | `init` ×5（button/pid/ringbuf/scheduler/swtimer，**语义各不相同**） | 需按模块限定作用域／改名，**不能删** |
    | **内部符号被导出** | `is_digit`（ctype 是标准库，parserexp/parserexpf 里是内部辅助）、`_vml_result_int`（dos/graphics/vmlsys 的 `static` 临时量） | 改为模块私有，不参与全局裸名解析 |

源头在 `Lib/shared/src/*.c`（`print_int` 实测定义于 `builtins.c:50` / `console.c:42` / `io.c:29`），
    **不是**改生成物 `.vml`（改了下一次 `gen_all_vml.sh` 就没了）。

- [ ] **第三类的根因已定位：编译器把文件级 `static` 输出成了全局标签**（第 3 层缺陷）
    - 实证：`Lib/shared/src/parserexp.c:20` 与 `parserexpf.c:14` 里的
      `static int is_digit(char c)` **本来就写了 `static`**（C 语义是内部链接），
      但生成的 `Lib/shared/parserexp.vml` / `parserexpf.vml` 里仍是顶格 `is_digit:` 标签。
      `_vml_result_int` 同理 —— `dos.c:8` / `graphics.c:23` 都是 `static`，`vmlsys.c:14`
      则是有意的全局（非 static），三者在 `.vml` 里长得一模一样。
    - **危害不是"多几份重复"**：`parserexp` 的内部 `is_digit(char)` 可能**遮蔽**
      `ctype.c:23` 的公开 `__stdcall int is_digit(int)` —— 两者签名与语义都不同。
    - 修法要动第 3 层（C 编译器给文件级 static 生成模块唯一名）。**但有个已知障碍**：
      `dos.c` / `graphics.c` 的 `asm("MOVE _vml_result_int, @R0")` 是**按字面名引用**的，
      改名还要同步改 asm 文本，而编译器无法解析 asm 字符串里的符号。
      可行方向：给 static 生成唯一名的同时**保留一个模块内的别名**，或让汇编器/链接器
      按模块作用域解析裸名（`UpdateAsmLabelReferences` 已按模块传映射，但用的是含全局条目的
      `combinedMapping`，存在选错的可能）。

- [x] **甲案已完成（2026-09-20，分两步提交）** —— 给文件级 static 生成模块唯一名
    - 第一步（行为中性，commit `6ec7e970`）：`Function` 加 `IsStatic`，`Parser.Declarations.cs`
      四处文件级函数注册点记录它；`CodeGenerator` 加 `_staticNames`/`_moduleName`/
      `SanitizeModuleName`/`Mangle`，`InitLabelCounter` 顺带记下模块名（原先只存数字偏移）。
    - 第二步（commit `c71bb724`）：接上改名 + `Parser.Declarations.cs` 补记**文件级 static 变量**
      （原清单只提到函数；`VariableDecl.IsStatic` 此前只被 static **局部量**使用）
    - ⚠️ **实现方式与原清单不同（实测更稳）**：清单原本要逐个改 14 个发射点 + 27 处
      `dataSection` 键访问，实做改为**全部代码生成完成后一次性改名**
      （`CodeGenerator.Core.cs` 的 `RenameStaticSymbols`，在 `BuildProgram` 之后调用）。
      理由是逐点 mangle 只要漏一处就"定义与引用对不上"，而单点全量改名**只需覆盖四类载体**
      即可复核完毕：数据段键、标签表、指令操作数（LABEL/MEMORY/INDIRECT）、asm 文本。
    - 覆盖面核查（逐项实证，非推断）：
      - `OperandType` 只有 5 种，持符号的 LABEL/MEMORY/INDIRECT **全在**改名范围内；
        取 static 函数地址（`int apply(int(*)(int))` 传 `sq`）走的是 MEMORY 操作数，已覆盖
      - `DataSection` 的**值**只可能是数值/数组/`DataString`/字符串字面量
        （`VMLProgram.cs:368` 起逐类型发射），**不存在"按值引用标签"这个漏网点**
      - C 编译器**不填 `Exports`**（`.export` 只从 VML 文本解析而来），故无导出名漏改
    - asm 兼容按计划做**词边界替换**（`ReplaceAsmWords`）。误伤面全库扫描：5 处命中
      **全是预期内的自引用**（`console.c` 的 `print_str_no_nl_impl`、`dos.c`/`graphics.c` 的
      `_vml_result_int`、`graphics.c` 的 `_gfx_fb`/`_gfx_w`），无助记符/寄存器误伤。
    - **实施结果（实测）**：`Lib/shared/*.vml` 跨文件重名的**第三类（static 泄漏）从 95 → 0**
      （逐名回源 `Lib/shared/src/*.c` 核对：0 个仍声明为 static 却顶格全局）。
      余下 **81 个全部是第一类「真·多份实现」**，要靠 R5 的链接器归属解析来收：
      `init`×5（button/pid/ringbuf/scheduler/swtimer）、`print_int`/`println_int`/… ×3
      （builtins/console/io）、`wcslen` 等 wcs/umem 族 ×2（wchar/wstring）。
    - 复验证据：`parserexp.vml`/`parserexpf.vml` 的 `is_digit` 已成 `parserexp__is_digit`
      （定义点 + 全部调用点一致）；`dos.vml` 成 `dos___vml_result_int` 且其 asm 文本同步改名；
      **反例通过** —— `vmlsys.vml` 的**非** static `_vml_result_int` 保持裸名。
      链库程序端到端实跑输出 `42`。
    - 全量测试：**1600 项 / 1592 通过 / 0 失败 / 8 跳过**（含 `SharedLibTests` 12/12）。
  - [x] **裸名 .linked 的语言感知解析（用户 2026-09-20 选定"甲案"，已实施）** —— 这才是本条的正题
    - **根因**：`LibraryLinker.GetLibFileIndex()` 按 basename 建全局索引、**首次命中即定**，
      而遍历顺序来自身 `Directory.GetDirectories(Lib)` —— **文件系统顺序**。NTFS 上是字母序，
      `basic` 恒排第 1（实测 25 个目录的枚举序：`basic, c, cpp, …, shared, swift, vml`），
      于是**任何语言**的裸名 `.linked "X.vml"` 只要 `Lib/basic/X.vml` 存在就解析到 BASIC 存根。
    - **三个决定性实验**（挪开存根/整目录再编译，项目内已还原）：
      | 实验 | 结果 |
      |---|---|
      | C 程序，挪开 `Lib/basic/builtins.vml` | `BASIC_NEWLINE` 2→0；**`c_newline` 0→1、`c_gcd` 0→1、`func_gcd` 0→1** |
      | Python 程序，挪开同一文件 | `BASIC_*` 410→396（只掉它的 14 个） |
      | Python 程序，挪开**整个 `Lib/basic`** | `BASIC_*`→**0**，但 **`c_*`→410、`func_*`→1107** —— 级联到下一家 `c`，Python 仍拿不到自己的 |
    - **危害**（按严重度）：① **跨平台不可复现** —— Linux/ext4 的 `Directory.GetDirectories`
      是 inode 顺序而非字母序，换平台就是另一种语言的存根胜出；② 每个语言都拿到**别的语言**的
      别名集、且**丢了自己的**（C 的 `c_*`/`func_*` 实测全缺）；③ 每个程序白链数百个无关别名。
      澄清一处：真正的 BASIC 运行时 `basiclib.vml` **并未**链入（`basiclib`=0、`BASIC_DIM`=0），
      所以"链入整套 BASIC 库"准确说是**链入了 BASIC 的别名命名空间**。
    - **修法**：`LinkLibraries(..., languageDir)` 新增参数；裸名按**固定顺序**解析 ——
      ① `Lib/<当前语言>/` ② `Lib/shared/` ③ 索引兜底（`GetLibFileIndex` 改为**按目录名排序**
      构建，消除跨平台不确定）；语言来源：`CompilerBase.LanguageDir`（默认 `Name` 小写，
      `CompilerPluginBase` 用其 `LibDirectory` 覆盖，如 C# → `csharp`），由 10 个调用点接上。
      同时把 `--dump-link` 补成**逐条打印每个 .linked 解析到哪个文件**（原先只印搜索路径，
      这正是上面排查一度只能靠"挪文件做对照实验"的原因）。
    - **验证**（实测）：C 程序 `BASIC_*` **410 → 0**、`c_*` **0 → 434**、`func_*` **0 → 1179**，
      实跑输出 `42`；Python 程序 `BASIC_*` **410 → 0**、`python_*` **69 → 410**；
      `--dump-link` 显示 C 的 72 条落 `Lib/c`、52 条落 `Lib/shared`，Python 的 162 条落
      `Lib/python`、139 条落 `Lib/shared`，**均不触碰其他语言目录**。
      完整性检查：逐语言比对 `Lib/basic/*.vml` 与 `Lib/shared/*.vml` ∪ `Lib/<语言>/*.vml`，
      **没有任何名字只在 `Lib/basic` 里** —— 因此索引兜底那一步对所有语言都不会再命中 BASIC，
      BASIC 泄漏是被**结构性**消除的（不只是 C/Python 两个抽样点）。
    - 全量测试：**1600 项 / 1592 通过 / 0 失败 / 8 跳过**（改链接器会波及所有语言，故必须全量）。

- 因此 R5 不只是清理性工作，它是修好链接器的**前提**：先确定每个函数**唯一的归属模块**
    （优先 `Lib/shared/`），链接器的裸名解析才有正确答案可言。
  - ⚠️ **文档勘误（2026-09-20 实测）**：本节原先写的排查手段
    「`VML_DUMP_LABELMAP=<path>` 环境变量可导出全局标签映射表（插桩点在 `LinkLibraries` 返回前）」
    **在代码里并不存在** —— 全仓 `grep -rn VML_DUMP_LABELMAP --include=*.cs` **零命中**，
    `LibraryLinker.cs:49` 只有个 `globalLabelMapping` 局部变量，没有任何 dumping 插桩。
    该环境变量设了也不产出文件。**要么补插桩，要么别再引用它。**
  - 本轮实际使用的替代手段（无需改代码，已验证够用）：**直接数生成物里的跨文件重名** ——
    逐个 `Lib/shared/*.vml` 取 `.text` 之后、形如 `^[A-Za-z_][A-Za-z0-9_]*:$` 的顶格标签，
    `sort | uniq -d` 即得重名清单；要判"是不是 static 泄漏"再回源
    `Lib/shared/src/<同名>.c` 查该名是否声明为 `static` 即可。（甲案的 95→0 就是这么量的。）
  - 现状：语言库（`Lib/python/shared.py`、`Lib/go/shared.go` …）是**绑定包装**
    （`asm("CALL strlen")` / `vml.Call("strlen")`），不是重复实现，不在本条范围内；
    真正的重复要在 `Lib/<lang>/stdlib.*` 与 `Lib/shared/src/*.c` 之间盘。
  - 注：v1.66.86 已删过 `Lib/c/*.c`（第二套 C 标准库源），本条属第二轮盘点。

- [x] **语言专用库的门禁 —— 专用语言的库只给专用的语言使用（用户 2026-09-20 定的规则）**
  - 现状盘点（实测）：GenLib 的模块表 `Lib/modules.json` 是**语言无关**的，于是 `GenModules`
    给每个语言都产出全部模块的包装器，其中两个是语言专用的：
    | 模块 | 属主 | 越界后果 |
    |---|---|---|
    | `basiclib` | `basic` | 每个语言目录都有 `Lib/<lang>/basiclib.vml`＝**BASIC 运行时的他语言包装** |
    | `builtins_kotlin` | `kotlin` | 同上，22 个目录全有 |
  - **危害已实证**：C 程序写 `#param lib("basiclib.vml")`，链接器交出 `Lib/c/basiclib.vml`，
    产物里真的出现 `basic_instr`(10) 与 `c_basic_instr`(7) —— BASIC 的运行时被交给了 C。
  - 修法分两层（缺一层都挡不住）：
    - **生成器**（`tools/GenLib`）：`ModuleDef` 加 `Owner`；`ModuleConfig.ExclusiveOwners`
      给出属主表（放代码里而非只手改 `modules.json`，因为配置被删会重建、属主信息必须自恢复）；
      `GenModules` 对非属主语言**不生成**该模块包装，并**删除**历史遗留的那一个确切文件名
      （只删本工具自己会生成的名字，不碰其他文件）—— 不删的话已有检出会永远留着违规文件。
    - **链接器**（`VMLAssembler/LibraryLinker.cs`）：`ExclusiveOwnerOf` 按**文件名**判定属主
      （`builtins_<lang>` → `<lang>`、`basiclib` → `basic`，与生成器同源），
      `ResolveLinkedFileChecked` 在**交出路径之前**拦截。这一层必需的证据：只删包装器之后，
      裸名会沿共享库回退命中 `Lib/shared/basiclib.vml`，C 仍拿到 `basic_instr`。
  - 实测各语言**只引用自己的** `builtins_<lang>`，不存在合法的跨语言引用，故收紧是安全的。
  - 复验：22 个语言的越界文件清零（`Lib/c`/`Lib/python` 73→71，`Lib/basic`/`Lib/kotlin` 73→72）；
    C 显式索取 BASIC 库 → **退出码 1 且不产出产物**（符合 R9）：
    `编译错误: 库 "basiclib.vml" 是 basic 语言的专用库，不能链接给 c …`；
    正常 C 程序不受影响（编译通过、实跑输出 42）。清理幂等（重复运行 GenLib 为 0 个待删）。
  - 注：这条与 R5 去重是**两件事** —— R5 管"同一功能多份实现该留哪一份"，本条管"专用库不许跨语言"。
  - [ ] **命名规范（用户 2026-09-20 定，待实施）** —— 让"是不是专用库"从名字上就能看出来：
    - 系统内置函数专用：**`builtin_<lang>`**
    - 外置的专用函数库：**`library_<lang>`**（现无此形式文件，属预留）
    - 二者都是**不共享**的专用库名称；共享模块不带语言后缀。
    - 现状与目标（`Lib/shared/src/*.c` 按文件名产出 `.vml`，见 `Lib/build_libs.sh:221`，故改名要连 `.c` 一起改）：
      | 现状 | 性质 | 目标 |
      |---|---|---|
      | `builtins_<lang>.vml`（22 个，≤15 行的 `#param lib(...)` 声明） | 语言专用清单 | → `builtin_<lang>.vml` |
      | `basiclib.vml`（88KB / 580 标签） | BASIC 运行时**实现** | → `builtin_basic.vml` |
    - **撞名与解法（用户已选定"合并"）**：`basiclib` 与 `builtins_basic` 都会变成 `builtin_basic`，
      故 BASIC 的清单并入聚合器，实现独占 `builtin_basic.vml`。
    - 改名波及面（已枚举）：`Lib/shared/src/*.c` 22+1 个、`Lib/*/builtin.vml` 22 个聚合器里的声明、
      `tools/GenLib/Program.cs:500`（聚合器模板里硬编码的 `builtins_{lang}.vml`）、
      `Lib/modules.json`（`basiclib`/`builtins_kotlin` 的 Source 与 Includes）、
      `LibraryLinker.ExclusiveOwnerOf`（届时 `basiclib` 特例可删，属主直接由 `builtin_<lang>` 模式得出）、
      `CompilerHelper` 里 `FindLibPath("shared","basiclib.vml")` 等硬编码点。
    - 改完后判定规则更简洁：**`builtin_<lang>` / `library_<lang>` 两种模式即语言独占**，
      不再需要 `ExclusiveOwners` 特例表。

- [ ] **R7 诊断尽量标出行列号，格式标准化以便对接 IDE**
  - 目标格式（GCC 标准，IDE 可直接解析）：
    `file:line:col: error: message [Code]` + 源码行 + 脱字符指示
  - 现状：`CompilerBase/CompilerError.cs` 的格式化已达标，**但位置信息拿不到** ——
    `CCompiler/ASTNode.cs` 的基类是空类（无任何位置字段），代码生成阶段的诊断
    只能报出文件名（行号 0 → `LocationString` 已改为省略 `:0:0`）。
  - [x] C：`ASTNode` 加 `Line/Column/SourceFile/SourceText`，标识符解析处填位置
        （`Parser.Expressions.cs` 的 `new Identifier` 是唯一构造点）
  - [x] `CodeGeneratorBase.ReportError` 增加带位置的过载
  - [ ] 其余 AST 节点（语句、声明、二元/一元运算）补位置，使所有诊断都能定位
  - [ ] 其余 21 种语言照此补齐

- [x] **R8 找不到库文件必须报错**（用户 2026-09-20 新增）
  - [x] 主程序声明的 `.linked` 解析不到 → `MissingLibraryException`，退出码 1、不产出 VML。
        实测：`.linked "totally_missing_lib.vml"` → `错误: 1 个 .linked 库文件找不到`
  - [x] **整条标准库找不到** → 报错。根因：链接完全依赖 `vmltool.config.xml` 恰好在当前目录
        （`VmlToolConfig.Load` 按 cwd 查找，`ResolveLibs` 把库文件路径填进 `options.LibraryPaths`，
        `libPaths.Count > 0` 是链接的闸门）。仓库根目录 → 36748 条指令；其他目录 → `libPaths` 为空、
        整条链接被跳过 → 35 条指令的空壳且不报错。现改为明确报错并提示用 VML_HOME 或回根目录。
  - [ ] **待办：库与库之间的引用暂仍只警告**。`Lib/<语言>/builtin.vml` 用裸名引用
        `device.vml` / `softfloat.vml` / `softdouble.vml` / `softint64.vml` / `builtins_<lang>.vml`
        （实际都住在 `Lib/shared/`），而测试环境（`CompilerTestHelpers`）的搜索路径里没有
        `Lib/shared`，解析不到。一律报错会牵连 20+ 用例（`Operators` × 多语言实测）。
        要收紧必须先补齐搜索路径，届时把这两处警告一并升级为错误。

- [x] **R9 有错误不生成 VML，警告照常产出**（用户 2026-09-20 新增）
  - 错误路径：语法错误 / 未声明变量 / 缺库 三类用例实测均 **exit=1 且无产物**（半成品也不留）。
  - 警告路径：正常程序带 31 条未解析目标警告，**照常产出** 36748 条指令。

- [x] **R10 全量测试防卡死、防死循环**（用户 2026-09-20 新增）
  - 现状：单用例保护已有且设计得当 —— `CompilerTestHelpers.RunWithTimeout` 用**专用线程**
        （不用 Task.Run，避免线程池自我饿死那类假阳性），默认 120s，超时抛 `TimeoutException`；
        且测试里所有编译器调用都集中在 `CompileCore`，外层有它包着。
  - **缺的是整轮保护**：`xunit.runner.json` 的 `longRunningTestSeconds` 原为 0（关闭），
        也没有 `--blame-hang-timeout`。实测出现过 **19m11s 的墙钟**（基线 4m39s），
        以及**残留 testhost 进程锁住 DLL**、整轮测试跑完日志只有两行、无任何结果就消失。
  - [x] `xunit.runner.json`：`longRunningTestSeconds: 60` —— 超 60s 的用例在输出里被标出
  - [x] CLAUDE.md 的关键命令补上 `--blame-hang --blame-hang-timeout 15m`：
        超时即杀宿主并输出挂起前的用例序列 + 转储，直接指出卡在哪个用例
  - [ ] 待办：`RunWithTimeout` 超时后线程**无法中止**（.NET Core 已无 `Thread.Abort`），
        只能标记后台线程任其跑完。若它正持着 `Lib/*.vml` 之类的文件锁，后续用例可能连环卡住 ——
        这才是"残留 testhost 锁 DLL"的根因，需要更彻底的隔离（如每轮用独立工作副本）。

- [~] **R6 syscall 接口全面加防护**
  - 现状：已实证可崩 —— `move R0 #-1` 后 `syscall #1`（打印字符串）直接
    `IndexOutOfRangeException` 崩在 `Syscall_PrintString`（只挡了上界 `a < memory.Length`，负数下标穿过）。
  - **不是"从零给 99 个 syscall 加防护"**：仓库里**已有既定写法**
    `if (addr < 0 || addr >= memory.Length) ...`（见 `Syscall.cs` 53/67/86/1020/1100/1151/1197/1375 行等）。
    问题是**有处理器没跟上**，判据客观（同文件里就有正确范例可对照）。
  - [x] 审计出**同一个 bug 的 8 个副本**，全部是"只挡上界、漏了下界"，负地址时判据恒真：
        `#1 PrintString`、`#2 InputString(写)`、`#70 DebugPrint`、`#72 Assert`、
        `#391 OutputWString`、`#392 InputWString(写)`、`#393 OutputUString`、`#401 TTY_WriteString`
        —— 其中 `#2`/`#392` 是**写入侧**，后果比读取更重。
  - [x] 8 处补齐下界防护；实测 `move R0 #-1` 逐个打这 8 个 syscall **均不再崩溃**，
        且正常打印无回归（`smoke hello 42 len=5`）、`Lang_VML`+`Infrastructure` 228 项全过。
  - [x] `Syscall.OS.cs`（10 处）与 `Syscall.FFI.cs`（4 处）已逐处审计完毕：
        - **13 处误报**（地址来自 `AllocateMemory(...)`，用户控制不到；或外层已有完整上下界校验）
        - **1 处真漏洞已修**：`FFI.cs` 的 `ReadNativeString(addr)` —— `addr` 是**从 guest 内存
          （FFI 参数块）里读出的指针**，完全由用户程序控制。原式
          `Math.Min(4096, memory.Length - addr)` 在 `addr` 为负时这个减法反而变大、min 取 4096，
          随后 `memory[addr + len]` 负下标崩运行时。已按下界防护处理（无效指针按空串）。
  - 验证：`Lang_FFI` + `Lang_VML` + `Infrastructure` **234 项全过**；正常打印无回归。
  - [ ] **C 侧 `VMLFast/VMLRuntimeC` 待加固，但当前无法验证**：实测 44 处 `mem[]` 访问、
        **零边界检查**（`vml_memory.c` 10 / `vml_runtime.c` 14 / `vml_syscall.c` 18 / `vml_device.c` 2）。
        两个障碍：① **没有任何测试覆盖它**（全量测试零引用 `VMLRuntimeC` / `vmlrun`）；
        ② 本机**无 C 编译器**（gcc/clang/cc 均无），无法构建验证。
        结论：不在无法验证的情况下写这份加固。建议单独一轮，先补测试覆盖或接上 CI 构建，
        再逐处加防护 —— 否则改完没有任何东西能证明它是对的。

- [ ] **顺带查实（未修）：文件级函数指针变量用「函数名」初始化时，整个声明被丢弃**（2026-09-20）
  - 形态：文件级 `int (*fp)(int) = sq;` → 产物里 **`fp` 与 `sq` 双双消失**，只剩一条
    **无定义的 `call fp`**。`sq` 是被"未使用函数消除"带走的（`= sq` 从未成为一次引用）。
    **这是静默产出错误代码，不是报错** —— 与 R1–R10 要治的同一类问题。
  - 触发条件已逐项实测收窄到**这一种**形态：

| 形态 | 结果 |
    |---|---|
    | 文件级 `int (*fp)(int);` ＋ 函数内赋值 ＋ 调用 | ✅ 正常（`fp: .word 0`、取址、`call R8` 间接调用） |
    | 文件级 `int (*fp)(int) = 0;` 且被使用 | ✅ 正常 |
    | 文件级 `int (*fp)(int) = (int (*)(int))0;` | ✅ 正常 |
    | 函数**内**局部 `int (*fp)(int) = sq;` | ✅ 正常 |
    | 文件级 `int (*fp)(int) = sq;`（初始化器是**函数名**） | ❌ 声明整体消失 |

- **非本次引入**：用甲案之前的 C 编译器（`bb5fb7ab`）跑同一探针，产出**完全相同**的错误结果。
  - 疑似根因：该类声明在注册阶段就没进 `Program.Variables`，于是 `fp(3)` 被当成对不存在函数
    `fp` 的调用。**根因未最终钉死**，修之前需先定位到具体是哪一步丢的。

### C 运行时对齐
- [x] CLC/STC 标志位修复
- [x] 浮点寄存器边界修复
- [x] IVT 基地址修复
- [x] MMIO 设备内存路由
- [x] 字符串类系统调用边界检查

### 翻译器补全
- [x] SPARC 浮点/64-bit/long 指令 (v1.66.31: 79/83 ~95%)
- [x] MSP430 浮点/64-bit/long 指令 (v1.66.31: 74/83 ~89%, 16位无HW浮点)
- [x] PIC24 浮点/64-bit/long 指令 (v1.66.31: 73/83 ~88%, 16位无HW浮点)
- [x] 全架构 SEXTB/SEXTH/CMOVZ/CMOVNZ/ROL/ROR 补全 (v1.66.29: 17/18 完成, v1.66.31 Wasm 达成 18/18)
- [x] 全架构 64-bit ANDL-SHRL 软件库调用 (v1.66.29: BaseTranslator.EmitCall)

### 测试基础设施
- [x] VMLToHex 单元测试 (v1.66.28: ToolAndHexTests.cs 流水线验证)
- [x] VMLTool CLI 测试 (v1.66.28: p10 测试, CLI 解析器需 AOT 兼容性)
- [x] 翻译器正确性验证 (v1.66.28: 187 测试, L0-L4 多层验证)
- [x] Fuzz 测试扩展至编译器级别 (v1.66.31: +2 C 编译器模糊测试, 5/5 通过)

### 代码质量
- [x] 统一 Builtins 测试 (Lua/Scheme/Ladder)
- [x] 统一 InitSimpleCompiler 初始化 (22/22 完成)
- [x] Python/Basic/Pascal 初始化统一
- [x] C 编译器序言/尾声 EmitPrologue (v1.66.28)
- [x] Forth 编译器 EmitExit 标注 (v1.66.28)
- [x] GenDev 生成器基类提取 (v1.66.28: GeneratorBase + C/C++, 其余 22 待迁移)

## 中期目标 (v1.68.x)

### 核心组件测试
- [~] C 运行时测试套件 (v1.66.31: C# 运行时 31 tests 完成, vmlrun 跨测试待 CI 集成)
- [x] VMLEmulators 测试 (PluginsAndEmulatorsTests: 20 tests)
- [x] VMLPlugins 测试 (PluginsAndEmulatorsTests: PluginManager + 插件接口)
- [x] 性能/基准测试框架 (BenchmarkTests: 11 tests, 汇编/翻译/编译/运行时/全流水线)

### 文档标准化
- [x] ISA 规范: global 指令文档
- [x] CHANGELOG 格式规范化
- [x] 贡献指南 (CONTRIBUTING.md — v1.66.31 更新: Trait 筛选 + 测试结构 + 提交规范)
- [x] 开发环境设置指南 (合并至 CONTRIBUTING.md 快速开始章节)
- [x] 测试分类 [Trait] 标注 (v1.66.31: Compiler/Translator/Infrastructure/Fuzz/Benchmark, 43文件)

### 大文件拆分 (God Objects)
- [x] Parser.Declarations.cs (2037 → 969 行) → Parser.Types.cs
- [x] Parser.Statements.cs (2004 → 909 行) → Parser.Structs.cs
- [x] CodeGenerator.Statements.cs (1774 → 1282 行) → CodeGenerator.Statements.IO.cs
- [x] Scheme CodeGenerator.cs (1420 → 812+614) → CodeGenerator.Expressions.cs (v1.66.28)

## 远期目标 (v1.69.x+)

### 工具链增强
- [x] GenDev 生成器统一基类 (v1.66.33: 23/23 全部迁移完成, Forth/Lua/Python/Scheme → GeneratorBase, 新增 EmitPins+EmitModuleStart/End 钩子)
- [x] GenLib/GenDyn 多线程加速 (v1.66.31+: Parallel.ForEach, 2-4x speedup)
- [x] 增量编译支持 (v1.66.33: IncrementalCache .vmlobj 时间戳缓存)

### IDE 完善 (当前 ~80%)
- [x] 编辑器: code folding, auto-complete (v1.66.22)
- [x] 项目属性编辑 UI (v1.66.33)
- [ ] 调试器: breakpoint, step, watch
- [ ] Git 集成

### 翻译器架构
- [ ] 翻译器基类定义架构无关接口
- [ ] 翻译器汇编语法规范化文档

施探宇 / VML

About

Releases

Contributors

Language(Optional)

Activities