通用代码转换器

将转换器构建或完善为一个分阶段的翻译流水线。优化目标应聚焦于语义保真度、诊断能力与渐进式交付，而非宣称“可转换全部内容”。

执行此工作流

1. 明确范围。

   • 厘清源语言、目标语言、运行时约束、支持的语言结构以及质量标准。
   • 在设计流水线前，至少获取或提取 3 个具有代表性的代码片段。
   • 明确定义“完成”的含义：是生成可编译输出、行为保持一致的输出、迁移脚手架，还是部分辅助转换？

2. 验证解析器前端。

   • 确认所需的 Tree-sitter 语法定义（grammar）已存在且可实际使用。
   • 首次前端探查时，优先选用官方预编译绑定或语法包；仅当官方制品缺失，或任务本身需要修改语法时，才手动编译语法。
   • 在硬编码遍历器（visitor）前，先检查实际的节点类型（node types）和字段名（field names）。
   • 从真实测试用例（fixtures）中提取一个可复用的解析器探查产物：根节点类型、关键字段名，以及一条查询/捕获（query/capture）示例。将其保留在测试或 fixtures 中，避免后续工作重复人工探索。
   • 若计划使用 Tree-sitter，请使用 old_tree 运行一次增量重解析（incremental reparse）检查，以证明该语法可作为编辑前端正常工作。将此视为一项能力验证，而非脆弱的微基准测试（microbenchmark）。
   • 将 Tree-sitter 视为具备增量解析能力的具体语法树（CST）前端，而非完整的语义编译器。

3. 将流水线拆分为显式的多个处理阶段（passes）。

   • 采用以下默认流程：

parse -> normalize -> semantic enrichment -> IR -> lowering -> emit -> validate

• 保持归一化（normalization）与语义分析（semantic analysis）分离。
• 将共享的中间表示（IR）逻辑与特定语言对（pair-specific）的降级（lowering）规则分离。
• 将代码格式化（formatting）与转换逻辑（translation logic）分离。

4. 围绕语义（而非表面语法）设计 IR。

   • 建模声明（declarations）、作用域（scopes）、绑定（bindings）、字面量（literals）、调用（calls）、控制流（control flow）、导入（imports）、类型（types）及诊断信息（diagnostics）。
   • 对存在信息损失或不支持的结构，显式地以诊断节点（diagnostic nodes）或状态标志（status flags）表示。
   • 尽早移除语法糖（syntax sugar），只要此举能简化下游的降级过程。

5. 首先实现一个窄而深的垂直切片（narrow vertical slice）。

   • 从单一源语言–目标语言组合开始。
   • 初始支持模块（modules）、函数（functions）、参数（parameters）、字面量（literals）、标识符（identifiers）、返回语句（returns）、调用（calls）及简单条件分支（simple conditionals）。
   • 每增加一类语法结构前，均需为其添加对应测试。

6. 有意识地处理语义差异（semantic gaps）。

   • 将每个语言特性分类为以下之一：直接映射（direct mapping）、解糖（desugaring）、运行时辅助函数（runtime helper）、需手动重写（manual rewrite required）、不支持（unsupported）。
   • 对导致行为变化或信息损失的重写操作，发出警告。
   • 绝不可静默丢弃异常处理、可变性规则（mutability rules）、异步语义（async semantics）或类型期望（type expectations）。

7. 基于结构化模型生成目标代码。

   • 优先采用带类型的（typed）目标语言模型，或目标语言专用的 emitter API，而非原始字符串替换（raw string replacement）。
   • 将命名（naming）、转义（escaping）和缩进（indentation）逻辑集中于 emitter 层实现。
   • 仅当任务明确要求时，才保留注释（comments）或源码映射（source maps）。

8. 在多个层级上验证输出结果。

   • 分别验证前端假设（frontend assumptions）与降级假设（lowering assumptions）。
   • 对代表性源码 fixture 执行重新解析，并断言解析器探查契约（parser-probe contract）保持稳定。
   • 对生成的目标代码执行重新解析。
   • 若工具链可用，对生成代码进行编译或类型检查（type-check）。
   • 针对行为保持型转换（behavior-preserving conversions），运行基于 fixture 的执行测试（execution tests）。
   • 至少包含一个明确的失败路径 fixture（failure-path fixture），其必须触发诊断信息输出。
   • 对 IR 及生成的输出进行快照（snapshot），用于回归测试覆盖。

9. 交付有明确边界的成果。

   • 返回支持的功能矩阵（feature matrix）、已知缺口（known gaps）、前提假设（assumptions）、警告（warnings）及后续步骤（next steps）。
   • 清晰说明当前成果属于脚手架（scaffold）、部分转换器（partial converter），还是可用于生产的功能切片（production-ready slice）。

交付如下成果物

• 针对架构类请求，返回：范围定义（scope）、流水线设计（pipeline）、IR 概要（IR outline）、特性映射分类法（feature mapping taxonomy）、验证计划（validation plan）及风险清单（risk list）。
• 针对实现类请求，首先编写最小可行切片（smallest working slice），随同提供可执行测试，并记录解析器探查所使用的前端依赖项及其精确版本（exact frontend dependency/version）。
• 针对评审类请求，优先关注语义漂移（semantic drift）、不支持的结构、对解析器形状（parser-shape）的隐含假设，以及缺失的验证环节。

仅在必要时查阅额外参考资料

• 如需了解模块布局、特性映射分类法及 IR 设计提示，请阅读 references/architecture-blueprint.md。
• 如需了解测试策略、回归防护门（regression gates）及发布标准，请阅读 references/validation-checklist.md。

遵守以下防护准则（Guardrails）

• 除非已明确定义支持的语言列表与支持的功能矩阵，否则不得将该转换器称为“通用”（universal）。
• 不得将具体语法树（CST）的结构等同于程序语义（program meaning）。
• 不得将所有转换规则置于单个 transformer 文件中。
• 在正确性与诊断能力尚未建立之前，不得承诺生成符合目标语言惯用法（idiomatic）的代码。
• 在未配备代表性 fixture 及验证机制的前提下，不得新增语言对（language pair）。

起始仓库结构如下

src/
  frontends/
  normalization/
  semantic/
  ir/
  lowering/
  emitters/
  diagnostics/
tests/
  fixtures/
  golden/