ttsc 维护者 Wiki

    开放问题

    本页记录从源码阅读中浮现、但代码本身没完全回答的问题，以及已知但未关闭的限制。每条标注证据指向，区分"代码已证明的"与"需进一步确认的"。这是给维护者的诚实清单，不是 bug 列表。

    已知限制（代码注释明确记录）

    Metro worker pool 不共享常驻宿主

    utility/serve.go:54 注释：跨独立 worker 进程共享一个宿主（Metro worker pool）仍在 issue samchon/ttsc#255 跟踪中。当前每个 Metro worker 各自起 TtscService/serve 宿主，没有跨进程复用。

    证据：utility/serve.go 的 serve 协议是单进程请求流；session.go:14 明说 transform 不能复用热程序（链接插件原地改 AST）。未关闭——是 #255 的范围。

    transform 不能复用热程序

    session.go:14：Session 提供 type-check 复用，不是 transform 复用。链接插件阶段原地改 source AST，所以 transform 每次编辑必须重建新程序。这是设计判断（#255），不是待修 bug，但它限制了 transform 的常驻性能上限。

    tsgo 升级脆弱点（需每次回归）

    以下不是开放问题而是已知脆弱面，列在这里因为它们是"代码依赖 tsgo 内部行为、升级可能静默破坏"的地方：

    • driver/emit_plugin.go:47 的 guardedEmitResolver：包住 const-enum 内联器的 GetConstantValue，对插件合成节点做 panic 恢复。这是对 tsgo checker 行为的脆弱假设——tsgo 改了 const-enum 内联或上下文类型计算可能改变其行为。
    • driver/emit_plugin.go:112 的 restoreOriginalDeclarationSymbols：手工把 binder symbol 从原节点拷到重建节点，绕过 emit resolver 的 nil panic。依赖 tsgo emit resolver 的 MarkLinkedReferencesRecursively 行为。
    • driver/emit_plugin.go:139 的 emit 管线手工组装：用 GetSourceFilesToEmit/GetScriptTransformers/PrintFileWithSourceMap 复现 tsgo emitter，绕过 tsgo 自己的 emitter。任何 tsgo emit 内部重构都可能断。

    未量化：这些补丁的边界条件（哪些插件构造的节点会触发、哪些 tsgo 版本改了相关行为）没有穷举测试，靠 typia/nestia 集成测试间接覆盖。维护者升级 tsgo 时应优先扩这块覆盖。

    文本重写的过度匹配风险

    driver/rewrite.go 的文本 splice 用正则匹配 emit 后的调用点。findSourceForOutput（rewrite.go:258）的注释记录了一个真实 barrel 误撞 bug 已被修。但文本匹配的根本风险——正则在某些 emit 形状下过度匹配或漏匹配——只能靠负向 twin 测试覆盖，不能被静态证明穷尽。新路径已转 AST 集成（emit_plugin.go），但旧文本路径仍在用（EmitAll/api-compile）。

    开放问题：文本路径还会服务哪些插件、何时能完全退役给 AST 路径，代码里没有明确的迁移终点。

    shim 完整性的遍历盲区

    shim_audit 的三层闸门能检测可命名性与组合可编译性，但检测不了运行时死胡同（Checker_getBaseTypes 在泛型边界 nil-deref，#246）。当前对策是手工运行时探针（packages/lint/test/shim/）。

    开放问题：哪些已暴露的图遍历 API 还没有完整性探针？审计无法枚举它们——这是个需求池而非可关闭清单。新暴露遍历 API 时必须手工加探针，但"现存 API 里有多少缺探针"没有自动盘点。

    单 checker 约束的性能代价

    driver/program.go:308 把 checker 池钉到 1 保证类型解析正确性。注释说明 parse/emit 仍并行，所以代价是"类型检查并行度"。但具体代价（多大项目上单 checker 比多 checker 慢多少）代码里没量化；基准矩阵有 checkers2/4/8 轴（见 基准测试），但那测的是 ttsc 整体 vs legacy，不是单 checker 约束本身的开销。

    缓存键的完备性

    buildSourcePlugin.ts::computeCacheKey 试图覆盖所有能改变二进制的输入（~50 个 Go 构建环境变量 + 源文件 + toolchain 身份）。但"是否真的覆盖了全部"无法证明——一个未被哈希、却影响 go build 输出的环境变量会导致陈旧二进制。GO_BUILD_ENV_KEYS 是手维护列表（buildSourcePlugin.ts:20），随 Go 版本可能需要补充。

    开放问题：Go 新增影响构建的环境变量时，没有自动机制提醒更新 GO_BUILD_ENV_KEYS。

    本 Wiki 的覆盖边界

    本 Wiki 深入了核心子系统（driver、插件宿主、shim、LSP、lint 引擎、代码图谱、ttsx、flags），但以下区域只做了概览级覆盖，需要时应回到源码：

    • packages/lint 的 720+ 条规则各自的语义（README 是权威逐条清单）。
    • experimental/ 下基准实现的内部细节（.codex/skills/benchmark/SKILL.md 更全）。
    • website/ Nextra 站点的组件实现（它是面向使用者的文档，不是维护者关注点）。
    • tsgo 自身的内部实现（在外部模块 github.com/microsoft/typescript-go，本仓库只经 shim 触碰）。

    如何用这一页

    遇到这些区域的工作时：

    1. 限制类（#255、单 checker）：是设计判断，别当 bug 修；改动要权衡其原始理由。
    2. 脆弱点类（tsgo 升级、文本重写）：改动前先扩测试覆盖，再动代码。
    3. 完备性类（缓存键、shim 探针）：把"补一个遗漏"当作持续维护，不是一次性关闭。

    接下来