Plannotator 推出 sem-jiff，按语义识别代码变更而非逐行对比

属于 Plannotator 的一部分，试试 Plannotator Inbox；一个帮你保持关注、更好地组织代码评审的收件箱。 diff 展示的是新增和删除的行。其中很多并不是真正的改动：一个函数被移动了，一个变量被重命名，代码被重新格式化，一段代码被抽出来变成了辅助函数。sem-jiff 会读取文件的旧版和新版，判断每一处改动到底是什么，这样评审者就可以跳过那些保留了原意的改动。它返回纯数据（semanticOperations、semanticFolds 以及对应的 patch），任何 diff 查看器都可以渲染。 src/pierre-types.ts 中的操作类型复制自 Pierre（Apache-2.0）。 改动 示例 移动 loadUser 被移到 saveUser 下方，内容未变 移动并编辑 被移动，途中有一行被修改 重命名 MAX_RETRIES 在各处都变成了 MAX_ATTEMPTS，其他没有变化 重新格式化 同一段代码换了排版（换行、Prettier） 重新排序 import 或成员被重新排序 提取函数 一个循环从 checkout 中移出，现在位于它调用的新函数 sumLineItems 中 内联函数 一个辅助函数被删除，其函数体被粘贴到调用它的地方 新增、删除、编辑 其他所有情况，按普通 diff 处理 它宁可什么都不说，也不说错：漏掉的改动会回退到普通 diff，而错误的标签会误导评审者。 npm install @plannotator/sem-jiff 用法 import { semanticDiffFile, languageForPath } from '@plannotator/sem-jiff'; const language = languageForPath('src/users.ts'); // 'typescript' const { semanticOperations, semanticFolds, patch } = await semanticDiffFile(language, oldText, newText, 'src/users.ts'); // 也把 patch 交给你的 diff 查看器，这样它的布局与操作对应， // 然后把 semanticOperations 绘制在它上面。 在 Node 中不需要其他东西。在浏览器中，把语法文件复制到你的应用旁边 （npx sem-jiff-copy-wasm <dir>），并通过 configure({ locateGrammar, locateRuntime }) 告诉引擎它们从哪里提供。选项、reviewSummary 和浏览器设置：docs/usage.md。 规则很严格，所以会漏掉那些在提取过程中代码被改写的提取函数。 加入一个决策模型后，引擎会就这些候选逐个询问它，每个文件一次。 你的密钥，你的账户；从服务器或你自己的机器上调用。 import { jevOpinion } from '@plannotator/sem-jiff/opinions'; const diff = await semanticDiffFile('typescript', oldText, newText, 'src/cart.ts', { secondOpinion: jevOpinion({ apiKey }), }); 或者两者都用：Jev 不确定时由 Clef（Cloudflare）来打破平局。 import { jevOpinion, clefScore } from '@plannotator/sem-jiff/opinions'; const secondOpinion = jevOpinion({ apiKey, tieBreaker: { ask: clefScore({ accountId, apiToken }) } }); 使用 Jev 时，每 500 行改动约 $0.0004。答案会被记住，所以再次打开同一个 diff 不产生费用。更多内容见 docs/usage.md。 在 TypeScript 实践提交上（187 个真实案例）：RefactoringMiner 找到 73 个，错 14 个；sem-jiff 找到 105 个，错 1 个； 加上 Jev 后找到 148 个，错 1 个。所有对比：harness/compare/README.md。 引擎如何测试：docs/verification.md。 TypeScript 和 TSX、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、Kotlin 和 Swift。 每个语言在此版本中暂不支持的内容见 CHANGELOG.md。 docs/usage.md：选项、reviewSummary、浏览器设置、第二意见、开发命令 docs/verification.md：如何验证、所有结果、Pierre fixture 中的已知勘误 docs/history.md：开发里程碑 docs/layout.md：源码布局以及如何添加一门语言 PACKAGING.md、CHANGELOG.md 许可 MIT 或 Apache-2.0，任你选择（LICENSE-MIT、LICENSE-APACHE），与 Plannotator 相同。 src/pierre-types.ts 和 Pierre fixture 为 Apache-2.0，复制自 Pierre。 wasm/ 中的 WebAssembly 文件（web-tree-sitter 及语法文件）保留各自的许可：见 THIRD-PARTY-NOTICES。