Deslop 如何按重复质量为重复代码簇排名
本文已按 0.35.0 更新。早期排名会乘以一个对数字节跨度项;当前排名仅使用重复质量。
只有当第一条发现恰好值得你花时间时,一份重复代码报告才算有用。大型仓库可能产生数百个簇。没有人会逐一审查它们,任何 AI 代理也不应把它们全部载入上下文。列表的顺序决定了什么会被修复,因此排名规则必须简单到可以手工验证。
公式
mass = canonical_node_count × max(visible_members − 1, 0)
第一个因子衡量参考出现的语法树大小,第二个统计额外的可见副本。复制的代码越多、副本越多,重复质量就越大。
克隆按重复质量降序排列,并列时以稳定 ID 决定先后。Same shape, different content 属于参考信息:其重复质量为零,没有克隆排名,排在所有克隆之后。
计算示例
| 簇 | 节点数 | 可见副本数 | 额外副本数 | 质量 |
|---|---|---|---|---|
| A | 120 | 2 | 1 | 120 |
| B | 40 | 4 | 3 | 120 |
| C | 200 | 1 | 0 | 0 |
质量 = 节点数 × 额外副本数。
A 和 B 的质量相同,因此由它们的稳定 ID 决定顺序。簇 C 只剩一个可见副本——其余副本被隐藏或排除——因此它不贡献任何重复质量。
为什么用语法树节点而不是行数
代码行数取决于格式。同一个函数在一种风格指南下可能是十二行,在另一种下可能是二十行,而一次格式化工具的运行就会让整份报告重新排序。语法树节点统计的是代码本身:语句、表达式、调用和运算符。Deslop 本来就用 tree-sitter 解析每个文件,因此参考副本的节点数无需额外成本即可获得,也不会因为有人重新格式化文件而改变。
参考副本是簇的规范出现。簇中的副本可能略有差异,例如重命名的变量或多出的一条语句,因此公式使用一个明确定义的副本,而不是平均值。
为什么是“额外”副本
一个函数的两份副本包含一份冗余实现,五份副本包含四份。公式统计的是你可以删除的副本:如果每份副本都替换为对一个共享函数的调用,visible_members − 1 就是可以去掉的数量。
这也是计数只使用可见副本的原因。如果你用 report_hide 标记生成的代码,这些出现仍留在分析中,但不再计入质量。手写代码与生成文件重复的簇仍会显示,因为它仍包含一份你写的可见副本。只与生成输出重复的簇则会降为零。配置文档解释了排除与隐藏的区别。
质量刻意忽略的因素
质量不衡量置信度或提取安全性,也不包含语言、文件历史、字节跨度或相似度乘数。重复百分比另行衡量被覆盖源代码行的并集。
这些排除都是刻意的:
- **不乘置信度。**相似度属于某一对特定的副本,而不是整个簇。簇的排名不应取决于恰好被评分的是哪一对。在 VS Code 中使用
--compare或 Compare To Canonical 可直接检查任意两份副本。 - **不按类别加权。**大小相同的一份完全相同副本和一份近乎相同副本排名相同。类别告诉你副本之间差异有多大;质量告诉你重复的代码有多少。
- **不用字节跨度。**旧的对数字节跨度项会奖励较长的标识符和字符串字面量。两个结构相同的簇可能仅仅因为一个使用了更长的名称而互换位置。去掉它之后,顺序只取决于代码结构。
- **不用文件历史或变更频率。**新近度和变更频率是有用的信号,但它们需要 git 历史,而且会让同一快照在仓库的不同克隆中排名不同。
一份仅凭报告就能重新计算出的排名,才是你在代码评审中可以信任的排名。公式的每个输入都包含在 JSON 输出中。
在报告中解读质量
JSON 报告中的每个簇都包含分类、出现位置、质量和排名。质量以整数输出,因此同一份代码生成的两份报告可以逐行比较。文本和 HTML 报告在每个簇旁显示同一数值,VS Code 面板也按相同顺序列出簇。如果某个簇的位置出乎意料,把它的节点数乘以额外副本数,再与排在它前面的簇比较即可。其中没有任何隐藏因子。
质量不是重复百分比
这两个数字回答的是不同的问题:
| 指标 | 问题 | 单位 |
|---|---|---|
| 质量 | 我应该先看哪个簇? | 语法树节点数 × 额外副本数 |
| 重复百分比 | 被分析的代码中有多少被报告的克隆覆盖? | 行数,重叠区间只计一次 |
百分比是 100 × duplicated_loc / analysed_loc,其中重复行数是每个文件中可见克隆区间的并集。它是 CI 阈值检查的数字。质量只决定列表顺序。一个仓库可能百分比很低,却存在一个质量极高的簇,而这个簇仍然是正确的入手点。
面向人类和 AI 代理的排名
相同的顺序出现在所有地方:CLI 的文本和 HTML 报告、VS Code 的簇面板,以及 MCP 服务器的 duplicates 工具。对 AI 代理来说,这正是保持上下文精简的关键。代理请求一份简短摘要,取最顶部的簇,决定是提取、复用还是接受它,然后再次请求。由于顺序是确定性的,对同一代码的两次运行会给出相同的列表。这让报告之间的差异保持可读,也避免代理对噪声做出反应。
如何处理排名第一的发现
高质量簇是重构的有力候选,而不是必须重构的指令。检查这些副本是否真的会一起变化。共享测试和调用者的大型复制块通常应该合并为一个函数。预期会逐渐分化的副本,例如测试夹具或代码迁移,可以通过配置隐藏,让它们不再占据列表顶部。无论哪种情况,决定权都在你手中。
修改之后,报告会刷新。如果副本已合并,该簇会消失,下一个簇上移。如果仍有一些副本存在,该簇的质量会随着每份副本的移除而下降,因此进度既体现在排名中,也体现在重复百分比中。
契约见 Rank by duplicated mass;报告排序实现于 report_weight.rs。