使用者痛点

• 迁移后代码看似通过编译，却可能悄然改变 SQL 语义。
• 大量相似的生成代码让人工 Review 失效，漏项或重复访问难以发现。
• AST 结构庞大，手工检查遍历完整性成本极高。
• 缺乏可量化的验证手段，只靠经验和直觉。话说回来，
• 即使测试通过也无法确认未覆盖的 AST 分支是否安全。

问题不是迁移代码能不能写。而怎么证明它是对的

AST 的旧 visitor API 不太好用，我们希望换成一套新的 API。

单看工程实现，这件事并不算难。AST 节点虽然很多，但大部分迁移代码模式重复。适合批量生成，也适合由 AI 完成大量样板工作。

真正让人不放心的不是代码能不能写出来而是写完以后怎样确认它没有静悄悄地改变语义。

在数据库内核里AST Visitor 是一层基础设施。它可能服务于 parser、binder、optimizer、formatter、权限检查、表达式重写等多个下游环节。迁移一旦出现偏差，未必会马上表现为编译错误。更可能是某个节点不再被访问、某个字段多访问了一次或者原本稳定的遍历顺序发生变化。代码表面上仍然合理，真正的影响却可能在更靠后的逻辑中暴露。

最初我们关心的风险主要有两类：

• 漏项或重复访问某个节点、字段或分支没有被遍历到，或者被意外遍历了多次。
• 顺序变化需要保持先后关系的 hook 改变了调用顺序。

这类问题很难只靠 code review 兜住。节点数量太多，人工很难在脑子里展开整棵 AST；大量生成代码又高度相似，review 很容易退化成对样板代码的走读。

我们开始尝试建立一套可执行的验证机制。让正确性更多地由程序化证据约束，而不是依赖人逐行确认。

从源码采集 AST 结构

要让后面的验证可信。不是写一套更复杂的逻辑来描述 AST，而是尽量直接地从源码中提取结构。类型、variant 和字段已经写在源码里采集工具只需要机械地把它们展开，作为后续代码生成的输入。

这里最关键的约束是少写逻辑。如果为了确认 visitor 有没有漏项，又手工实现一套节点分类、递归关系和特殊规则。那么只是把原来的审计问题搬进了验证工具：要相信验证结果，就得先完整审计这套一样复杂的逻辑。

源码分析应该保持短而直接沿用语法分析得到的类型定义。 枚举 struct、enum、variant 和字段，让产出能够回到对应的源码位置。一个声明对应一条结构记录，必要的排除项显式列出。不在采集阶段推断遍历语义，也不复制 visitor 的特殊顺序。

这种做法的可信度来自映射关系足够简单。需要审计的是少量通用的源码提取规则，而不是另一套与 AST 同规模的手写模型。它提供的是一份可追溯、可审计的结构输入;visitor 实际怎样遍历这些结构，则交给运行时观测和后续比较回答。

把运行时观测和等价性判断分开

扫描源码以后下一件事是把 visitor 的实际运行行为记录下来。这里最关键的设计，是把观测和比较分开。不要生成代码同时承担正确性判断。

a) 生成代码只负责产生 trace

• 忠实记录进入了哪个 hook、看到了哪个节点还有事件发生的次数和顺序。它不判断某个事件是否应该出现，也不在记录时排序、去重或过滤结果。

b) 等价性判断由另一套独立比较器完成

• 比较器读取新旧 visitor 的 trace，再根据遍历契约判断访问项目、次数和关键顺序是否一致。

明确 Trace 应该怎样比较

观测层能够稳定地产生数据以后下一个问题才真正具体起来：什么样的差异算 visitor 语义变化？

a) 项目集合 vs 多重集

最初最容易想到的是比较“访问到了哪些项目”。这可以发现某个节点或 hook 在一边出现、另一边没有出现。但集合会丢掉访问次数：一个节点访问一次和访问两次在集合里看起来完全相同。需要比较多重集。或者直接比较保留次数的事件记录，以捕获漏项与重复访问。

b) 顺序敏感性检查

• 先见到定义，再处理引用；
• 遇到第一个匹配项便提前退出；
• 依靠 enter 和 exit 的嵌套关系维护状态。

• A) 访问项目是否一致；
• B) 访问次数是否一致；
• C) 对顺序敏感事件序列是否一致；
• D) enter/exit/skip/提前退出等控制行为是否一致。

"等价"并非要求新旧实现完全相同，而是要求它们在约定可观察遍历行为上没有未解释差异。旧 API 在这里充当历史基线，但若新实现有意修复旧行为或改动契约。这类差异应显式记录，而非被悄悄过滤掉。

让失败能够直接定位

If comparator reports a mismatch,developers need precise context rar than a simple boolean.

• The failing test or input name.
• The exact missing or duplicated event.
• The hook whose order changed.
• The AST node path associated with event.
• The first point where new and old traces diverge.
• A small surrounding context .

This diagnostic requirement pushes back to observation layer: events must carry node paths;traces must remain ordered;no deduplication may happen early. Thus,trace protocol itself must support rich failure reporting.

主要内核概览

The loop works for any given AST:

1. Create AST from source code .
< html

old_visitor.trace → compare → report
new_visitor.trace → compare → report
...


Oops ignore this part - we continue narrative without code block.