ServerPackCreator 代码审计实践:测试深度、变异验证与缺陷防御
ServerPackCreator 代码审计实践:测试深度、变异验证与缺陷防御
本篇技术指南围绕开源仓库 ServerPackCreator 中的核心审计文档 claude-docs/ANALYSIS-AUDIT.md 展开。该文档是一份持续累积的代码分析审计证据日志,记录了 2026-09-05 至 2026-09-25 期间对 -clientside、-grinder、-api、-app 及多个插件模块的十二轮测试深度与缺陷分析。读完本文,你将掌握这套审计体系的方法论内核:如何区分"覆盖率"与"测试深度"、如何用变异验证(mutation verification)证明一个测试真的能拦住回归、如何识别"通过却什么都没断言"的伪 guard,以及一份可直接复用到其他项目的审计检查清单。文中所有结论均可在仓库源码与测试中逐一核对。
一、文档定位:一份只追加、永不覆盖的证据日志
ANALYSIS-AUDIT.md 自述为 "accumulating evidence log",维护规则只有一条:Appended to, never overwritten——只追加,从不覆盖。每条记录带日期,测量数据、变异验证结果与 "verified clean, do not re-litigate"(已验证干净,勿再翻案)清单永久有效。
这一设计解决的是长期审计项目的两个核心问题:
- 结论可追溯:任何一天发现的问题、给出的修复、以及"为什么判定为不是问题"的理由都留档,后人不必重新推导。
- 避免重复劳动:每轮审计末尾的 "verified clean — do not re-litigate" 清单明确列出已被证伪或已确认无害的疑点(例如 CurseForge API key 只出现在构造参数与 headers 映射中、
VerdictStore.hasVerdictFor不是缺口、阶梯排序 16 级全部被 pin),下一轮审计直接从更短的疑点清单开始,而不是从头再来。
文档与同目录下的 claude-docs/REFACTOR-AUDIT.md 形成分工:后者负责提交卫生与约定合规(每个 fix: 提交前必须有对应的红色 test: 提交),前者负责"测试到底断言了什么、改动的代码还有什么没被覆盖"。两篇文档同日的条目互相交叉引用而非重复叙述。
二、审计方法:镜头、度量与全仓扫描
2.1 每轮审计先声明"镜头"(Lens)
每轮审计开头会明确本次的观察视角,例如:
- 2026-09-05:"guards asserting a unit no caller reaches, tests constructing the value under test, and partially-pinned ordering invariants"——寻找没有任何调用者到达的 guard、构造被测值本身的测试、以及只被部分 pin 住的排序不变量。
- 2026-09-09:"what the relaxed rule now lets through, functions that are not total, and stated orderings nothing asserts"——宽松规则放行了什么、哪些函数不是全函数(total)、哪些文档声称的排序没有任何断言。
- 2026-09-20 第三遍(迭代 3):"deliberately looked where the first two had not: at the consumers of the value"——故意去看前两遍没看的地方:值的消费者。
这种"每次换一个镜头"的做法保证多轮审计不会在同一层面空转。
2.2 度量优先于推理
文档反复强调两个实测事实的价值。2026-09-11 迭代 1 开头就记录了:**fabric-api-0.116.17+1.21.1.jar(从真实构件读取)**的顶层描述符是 id = "fabric-api"、provides = ["fabric"],它随包携带 49 个嵌套 jar,而 fabric-resource-loader-v0 只以 META-INF/jars/fabric-resource-loader-v0-0.116.17.jar 的形式存在。这个测量直接决定了一个审计发现的方向(见下文 A-1 的 unless 分支问题)。
另一个典型测量:ServerPackUpdater.protects() 在单次更新中对每个文件调用一次,看起来像是热循环不变量的反面教材。实测 20,000 条路径后,protects() 全程 12.0 ms(其中构建 TreeSet 的 getter 占 2.5 ms),把列表提升到循环外一次反而要 12.7 ms——结论是"不值得缓存"。文档称这是 "the B30 lesson again — measure before optimising, and record the negative result so nobody re-opens it":负面结果也要记录,防止后人重新打开这个优化问题。
2.3 全仓孤儿扫描(orphan sweep)
2026-09-05 的方法注记说明了一个关键陷阱:孤儿扫描必须全仓库进行,而不是单模块。仅扫描 -clientside 的 src/main 就报告了 17 个误报,因为 ClientsideListEditor、BootArtifacts、AttemptDirectory 会被 -app 和 -grinder 调用,且方法引用(::current、cache::evictUnusedSince)不是调用语法。统计调用、:: 引用与 override 声明后,30 个候选缩减为 4 个,其中 2 个是文档化的测试缝隙(test seam)、1 个被驳回。
三、测试深度与覆盖率的边界:guard 应该 pin 什么
文档最重要的方法论区分是:覆盖率回答"有多少行被执行过",测试深度回答"一个错误值会不会被测试抓住"。后者才是审计的关注点。
3.1 手写 18 字段映射只断言 5 个(M-1)
Grinder.kt 中 store.record(GrindVerdict(...)) 从 LoaderVerdict 手工复制 18 个字段。唯一驱动 grind 并检查记录结果的 GrinderTest 只断言了 bootedLoader、declaredClientSide、declaredServerSide、jarScan、suggestedEntry 五个,未断言的有 verdict、declared、firedRule、decidedBy、stagedDependencies、filenamePattern、detail。更糟的是:所有报告、CSV、查询与过滤测试都通过 grindVerdict(...) 辅助函数直接构造 GrindVerdict,所以没有任何测试能看到"生产者填错字段"的场景——这正是 unsatisfiedLabel 能通过测试却让两个平台都喂给它错误 slug 的同类形状。
失败场景很具体:把 filenamePattern = verdict.suggestedEntry,或把 declared 与 declaredServerSide 互换,整个测试套件依然全绿,而 /as-properties 与报告表会发布错误的列——其中 verdict 是发布闸门(publication gate)读取的字段,危害最大。
修复(同日):新增 RecordedVerdictMappingTest,用一个 fake CandidateVerifier 返回 LoaderVerdict 全部 18 个字段携带各不相同哨兵值(SENTINEL)的 ClientsideReport,跑 Grinder.grind 后逐一断言。变异验证确认两个预测的错误接线都会失败:
filenamePattern = verdict.suggestedEntry -> "'SENTINEL_FILENAME' was dropped by the mapping"
declaredClientSide = verdict.declaredServerSide -> "expected: <REQUIRED> but was: <UNSUPPORTED>"
文档强调:"Distinctness is the mechanism, not decoration"——不同字段必须用不同的哨兵值,因为相等的值检测不出交换。两个 DeclaredSupport 字段故意取不同常量,且没有两个枚举哨兵共用名字。
3.2 四臂偏好的内部次序(M-2)
BootCandidateSelector.kt 的 pickDependencyFile 背后是一个四臂偏好阶梯(preferenceLadder):
pickFrom(satisfying.filterNot { locked }) // 1 可获取 且 满足约束
?: pickFrom(files.filterNot { locked }) // 2 可获取 但 违反约束
?: pickFrom(satisfying) // 3 被锁定 但 满足约束
?: pickFrom(files) // 4 全部兜底
当时的测试覆盖了"锁定 vs 可获取(无约束)"(臂 1/2 vs 3/4)、"可获取性优先于精确 loader 匹配"、以及"全部锁定仍返回文件"(臂 4),但臂 2 与臂 3 的相互作用没有被覆盖——没有一个测试让"锁定但满足约束"的文件与"未锁定但违反约束"的文件竞争,而这是唯一能把臂 2 和臂 3 区分开的场景。把臂 2、3 交换后套件依然全绿,选择器会重新偏好不可获取的文件,重蹈 2026-09-04 修复过的 306612 / Fabric-API 拒绝事件(症状是一个 ERROR 裁决覆盖掉决定性的那个)。
修复(同日):BootCandidateSelectorTest 新增两个测试——anObtainableFileBeatsALockedOneThatSatisfiesTheConstraint pin 住"可获取性压过版本约束",betweenTwoObtainableFilesTheConstraintStillDecides 作为反向砝码防止可获取性从"偏好"变成"覆盖"。变异验证:交换两臂后失败于 expected: <lib-0.9.0.jar> but was: <lib-1.5.0.jar>。
3.3 纯决策应当被直接 pin
文档明确的项目偏好:纯函数决策直接做单元测试,而不是通过间接的集成路径。典型例子:
- 2026-09-08 的 A-4:
backtrackReason——区分"该项目没发布任何可用东西"与"我们把它们全部排除了"的谓词——只能通过两条 staging 路径到达,且三个分支只被覆盖了一个。它是接收ProjectFiles和Set<String>的纯函数,是典型的单元测试领地。 - 2026-09-09 的 M-2:
BootVerifier.preventionCauseFor不是全函数,对空 map 会抛NoSuchElementException(PreventionCause.entries.first { it in causes })。当时唯一的调用点refuseForMissingDependencies在到达前就返回null了,所以不可达——但"今天不可达"正是这个仓库付过两次学费的形状(UnmetReason.explain返回null导致两处日志在后续编辑后会打印字面null.)。修复:空集合返回PreventionCause.HOST(与所有其他预防点一致的"最大声解读"默认值)并 pin 住。 - 2026-09-08 的 A-5:五个
UnmetReason值中有两个(DISTRIBUTION_LOCKED、UNRESOLVED)只在渲染拒绝字符串处被断言(DependencyLabelTest),从未在"选择原因"处被断言。修复通过真实 staging 到达这两个值,并意外暴露了一个不忠实的 fake:测试下载器忽略了downloadUrl,导致被锁定的文件"被下载成功",用例变成了 backtrack。
3.4 从 entries 派生,而不是手写清单
2026-09-09 的 M-3 与 M-4 指向同一类腐烂:枚举裁决列表被手写死,新成员悄悄漏掉。
VerdictPublicationTest断言"损坏的主机不发布",专门防二十行ERROR洪水,但 2026-09-09 新增的LOCKED与UNVERIFIABLE恰好在它要保护的人群里,却不在任何断言中。VerdictColumnTest.attemptRetentionAgreesWithVerdictRetention迭代listOf(CONFIRMED, INCONCLUSIVE, ERROR)断言keepsLogs,自称是 drift guard,却只覆盖六个裁决中的四个。
修复方式一致:从 Verdict.entries 派生。onlyConfirmedIsEverPublished 驱动渲染器跑过 entries 的每一行,断言只有 CONFIRMED 被发布;everyVerdictIsClassifiedForRetention 按 grindRan 分区断言——一个第七种裁决被加进来时会自动进入断言范围,无需编辑测试。可以对照 Verdict.kt 验证:六个裁决各自的 keepsLogs 与 grindRan 都是显式声明的构造参数,其中 LOCKED/UNVERIFIABLE 因"没有容器运行、无物可留"而 keepsLogs = false。
四、变异验证:唯一能证明 guard 有牙齿的方法
贯穿全部十二轮审计的最强方法论,是变异验证:故意破坏生产代码,观察哪个 guard 变红。文档的态度斩钉截铁:"Mutation is not a finishing flourish here; it is the only way this project's guards have been shown to have teeth."
4.1 一打变异实例
| 审计轮次 | 破坏方式 | 结果 |
|---|---|---|
| 09-05 M-1 | 交换 filenamePattern = verdict.suggestedEntry、declaredClientSide = declaredServerSide |
RecordedVerdictMappingTest 红,消息精确到字段名 |
| 09-05 M-2 | 交换臂 2 和臂 3 | expected: <lib-0.9.0.jar> but was: <lib-1.5.0.jar> |
| 09-05 阶梯 | 把 mixin-apply-failure 提升到 client-only-class 之上 |
16 级阶梯的整体 pin 失败 |
| 09-08 A-3 | 交换 nestedVersions(...) + scanned… 操作数 |
优先级 guard 失败于 create-6.0.8.jar 代替 create-6.0.10.jar,套件其余部分无感知 |
| 09-09 M-5 | addIfAbsent → add |
并发学习者 guard 失败 |
| 09-09 L-1 | 提升约束层级 | anExactVersionTheConstraintRejectsBeatsANeighbourItAccepts 失败 |
| 09-11 A-2 | 强制 fromCurseForge 返回 RELEASE |
两个新的 CurseForge guard 失败 |
| 09-11 A-3 | 把频道过滤器提升到可用性闸门之上 | 其 guard 失败 |
| 09-20 M4 | normalize() 停止转换 \\→/;prune 改用 File(relative);startsWith("$protected/") 放宽为 startsWith(protected);zip 过滤器改为仅当开关开启时安装;readManifest 停止捕获 |
各自对应的 guard 逐一失败 |
| 09-23 A-6 | 移除"已回收 id 集合" | anOrphanWithBothAnArchiveAndAnExtractedDirectoryIsReclaimedOnce 失败 |
| 09-25 A7 | 移除 PortAllocator.allocate 的 @Synchronized |
concurrentAllocationsNeverCollide 失败 |
4.2 三条铁律
- 先写红色 pin,再写修复。文档中的每轮修复几乎都遵循 "red-pinned first":先写一个在现存(有缺陷的)代码上变红的测试,再修复让它转绿。09-20 的 H1 修复就是这样:
b57efd7e2先写红 pin,5bc4e2743修复。 - 不能编译的变异毫无意义。2026-09-11 迭代 1 的记录提供了一个差点造成错误结论的真实事故:A-2 变异的第一轮运行报告了"错误的"失败测试——因为一次正则编辑留下了一个孤立的
when主体,构建从未编译,解析器愉快地读取了上一轮的test-resultsXML。变异检查的输出看起来和真实结果一模一样。因此:变异运行前必须清理build/test-results,且把"无结果"当作与"零红"不同的独立结果对待。 - 运行 pin 后才能提交。09-08 的记录总结:新增 guard 中有两个先红,且两次故障都在测试本身——一个比真实更强大的 fake,和一个函数永远不会被问及的问题。二者在读到失败文本前都像代码缺陷。
五、HIGH 缺陷案例研究
5.1 首次生成 + 更新开关:本地 variables.txt 丢失(H1,2026-09-20)
这是文档中最具代表性的"隐蔽回归"案例。ServerPackHandler.kt 在生成流程中先写 manifest.json,而 ServerPackUpdater.isUpdateRun 恰好用"manifest.json 是否存在"来判断本次是否为更新——于是在一次运行的中间,isUpdateRun 从 false 翻转为 true。
首次生成时的序列是:
:359写入压缩版variables.txt(preserve为 false,因为文件还不存在);:375本应用本地变体覆盖它——只有本地变体携带用户配置的SPC_JAVA_SPCJava 路径——但此时variables.txt已存在且受保护,isUpdateRun为 true,preserve返回 true,本地变体永远写不出去。
结果:数据包保留的是压缩包里的副本,其 SPC_JAVA_SPC 已被替换成字面量 "java"(ServerPackProvisioner.kt:500-503)。该缺陷用探针实测确认(同一配置在 @TempDir 中生成两次,仅切换开关):更新开启 + 首次生成 + 期望 zip 时,variables.txt 不含配置的 Java 路径;对照组则包含。
修复:在写入任何文件之前一次性快照"哪些 provisioned 文件已经存在",图标、server.properties、运行文件决策全部读取同一份快照。preserve lambda 闭包捕获快照而非重复推导,彻底消除"同一个值在一次运行中读两次可能不一致"的意外。对照 ServerPackHandler.kt 可以看到 preserved 集合在写入前构建的注释性证据。
5.2 Content-Disposition 头注入(A-2,2026-09-23)
ModPackController.kt 原实现直接把客户端提供的文件名插入响应头:
.header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"${modpack.get().name}\"")
ModPack.name 是上传文件的原始文件名——攻击者可控,且 landingName 现在故意保留原名(只剥离路径分隔符)。含 " 的名字会提前闭合引号,含 "; 的能追加第二个参数。该端点无认证且带 @CrossOrigin("*");Tomcat 拒绝 CR/LF,所以这是头参数注入而非响应拆分,但仍是公共路由上未校验的数据进入响应头。
修复经历了三次尝试,中间一次是文档明说的教训:用 Spring 的 ContentDisposition.parse 解析头再与原文件名比较,对注入也通过——因为解析器是宽容的,能从转义与未转义两种形式中恢复出 evil".zip"; filename="other.exe。最终断言落在原始头上:移除转义对后必须恰好剩两对引号。修复后的代码已改为 ContentDisposition.attachment().filename(...).build().toString()(RFC 6266 编码),可在 ModPackController.kt 中看到。
5.3 错误形状的 200 读作"无裁决"(A-3,2026-09-06)
GrinderClient.readVerdicts 在文档既非数组、也不携带 verdicts 数组时返回 emptyList()。于是一个返回 {"error":"…"} 加 200 的代理或未来守护进程,会被读成 FetchResult.Ok(emptyList()),标签页报告 "0 confirmed, 0 other verdicts"——与一个真正什么都没磨的 grinder 无法区分。讽刺的是,已有 guard 叫 reportsAnUnparseableBodyRatherThanReturningNothingFound,但它只覆盖非 JSON,它名字所声称的案例正是它漏掉的案例。
5.4 grinder 文本进入 HTML 解释型 Swing 组件(A-2,2026-09-06 + 2026-09-25)
这是一个安全发现:slug 与 detail 来自 mod 元数据,而 grinder 守护进程无认证。Swing 的 HTML 子集会获取远程图片,所以一个精心构造的 mod 名能让 SPC GUI 发出外联请求。2026-09-25 的 servertest 分支又确认了三个 HTML 注入面:包表格(getColumnClass 返回 Object,HTML 禁用渲染器从未被咨询,实测 rendered view is HTML = true)、warn() 对话框(String 消息到 JOptionPane 会安装 HTML 视图)、以及控制台子标签标题(PLAUSIBLE,未测量)。
5.5 启动编排未测试 + 下拉框接线未 pin(A1 / B1,2026-09-25)
- A1:
ServerTestTab.launch约 60 行决策——拒绝已在运行的包、分配端口、仅当 RCON 开启时分配第二个端口、借用server.properties、构建会话、启动前注册、无论运行如何结束都恰好归还一次端口与文件——完全未覆盖。givenBack的AtomicBoolean之所以存在,正是因为归还路径可达两次。这是 MVC 层面的发现:"视图持有控制器"。修复:把编排提取到core的ServerLauncher/LaunchOutcome,7 个 guard 覆盖拒绝、端口数、借用失败路径与双重归还;RealPackBootTest改走生产路径(对 NeoForge fixture 实测Done (3.995s)!,fixture 逐字节不变)。 - B1:
PackListPane的scriptChoice.addActionListener { onScriptChanged() }——删掉这一行整个套件依然全绿(实测)。下拉框会变成摆设。既有选择 guard 直接调用pane.show(...),那是回调最终造成的结果而不是回调本身。修复:通过真实组件设置下拉框选择并断言回调运行——唯一穿越监听器的断言。
六、MEDIUM / LOW:边界用例与非全函数
6.1 版本可读性门:toIntOrNull 而非"全是数字"(A-1,2026-09-08)
VersionConstraint.numbersOf 的结尾是 component.takeWhile { it.isDigit() }.toIntOrNull() ?: 0。刚修过的缺陷(Balm 26.2.0.7 被读成 <a href="https://link.gitcode.com/i/63bfeb663c738f26c93173020ff0e6d8" target="_blank">0, 2, 0, 7])通过第二扇门回归:readableVersion 承认任何"全数字"组件,但 toIntOrNull 对超过 Int.MAX_VALUE(10 位数字)的组件返回 null,?: 0 于是把该组件变成 0 而不是"不可读"。一个携带日期或 CI 计数器的版本——1.20260908120000、2026.9.8.120000——会像其最大组件是 0 一样参与比较,低于几乎任何边界。这正是当初制造 47 个裁决的缺陷形状。修复方向是"一个全数字但解析不出的组件不可读,于是 satisfies 接受、没有任何东西被判定在一个我们无法容纳的数字上"——在 [VersionConstraint.kt 的 readableVersion/readableComponent 中可以看到这套"prose 是常态而非边界"的完整论证。
6.2 LearnedModIds 的线程安全与空条目(M-5 / L-2,2026-09-09)
LearnedModIds.kt 的类文档声称"Thread-safe: the grinder shares one instance across its grind workers",GrindPool 也确实让 N 个 worker 共享一个实例。该批次把值类型从不可变 String 换成了 CopyOnWriteArrayList,由 computeIfAbsent 后的 addIfAbsent 变更——组合本身正确(computeIfAbsent 原子、addIfAbsent 同步),但值得 pin 住。另一个 LOW:restore 在过滤 refs 之前执行 computeIfAbsent,遗留文档里一个 id 对应的 JSON null、数字或空数组会留下空的 CopyOnWriteArrayList,snapshot() 把它序列化为 "id": [] 使文件不断累积毫无断言的条目。修复:先过滤、后认领条目。
6.3 大小写折叠与 Locale.ROOT(M2/M3,2026-09-20)
ServerPackUpdater.prune 的 keep 集用 lowercase() 折叠比较。审计初判"在大小写敏感的文件系统上是错的",但第二遍撤回了这个结论(见下节)。ServerPackUpdater.kt 现代码中的注释完整记录了论证,且四处 lowercase() 全部显式传入 Locale.ROOT——Kotlin 无参 lowercase() 使用默认 locale,在 tr/az 下 I 会折叠成无点 ı。
6.4 嵌入式 mongod 版本三处拼写(A-3,2026-09-23)
EmbeddedMongoAvailable.kt:64 声明 MONGOD_VERSION = "8.0.5" 却从未使用;探针从 Version.Main.V8_0 启动(flapdoodle 的 Main 指向任意 8.0.x);两个测试各自硬编码字符串 8.0.5。"决定是否跳过"与"决定运行什么"是两个值,中间还躺着一个看似把它们连起来的死常量。这正是仓库自己的教训——duplicated knowledge drifts toward whichever copy is easier to reach——修复为一个常量被两边引用,探针从同一字符串派生版本名。
七、审计的自我纠错:撤回、反转与"错误是有用的部分"
这套审计体系最独特的品质是坦然记录自己错了,且把纠错过程当作最有价值的产出。
7.1 M2 撤回:大小写比较必须两面论证(2026-09-20)
初判说 prune 的 keep 集大小写不敏感比较"在大小写敏感文件系统上是错的",并建议不折叠。撤回理由:在大小写不敏感的文件系统上(Windows、macOS 默认),Mods/Alpha.jar 与 mods/alpha.jar 是同一个文件,而 prune 在复制之后运行。不折叠时,复制刚写出的条目匹配不上旧 manifest 条目,会被判为陈旧并删除本次运行刚生成的文件。折叠的代价是 Linux 上偶尔残留陈旧文件;不折叠的代价是 Windows 上删除新生成的文件。欠修剪才是安全方向。文档的总结发人深省:"这个发现命名了一个真实的非对称性,然后提出了在破坏性方向上解决它的修复。一个改变删什么的建议必须在两个文件系统上都论证之后才能落笔,而不只是论证触发它的那一个。"
7.2 A5 撤回:Kotlin lowercase() 是 locale 安全的(2026-09-06)
初判声称 ClientsideEntryInjector 的 lowercase() 对 locale 敏感。实际:Kotlin 的 lowercase()(自 1.5 起)正是为了取代 locale 敏感的 toLowerCase() 而存在,编译为 toLowerCase(Locale.ROOT)。在土耳其语默认 locale 下实测:Java toLowerCase() → ıceberg-,Kotlin lowercase() → iceberg-。为它写的 guard 首跑即绿,这正是发现真相的方式;guard 被保留为防 lowercase(Locale.getDefault()) 或 Java 互操作回归的 pin。
7.3 B-3 反转:断言形状的 guard 会骗人(2026-09-11 迭代 2)
迭代 1 声称 retry-order 修复已落地,迭代 2 按其要求补行为级 guard,结果对"已修复"的代码变红——从而暴露迭代 1 的 M-4 是个假发现。文档的总结值得背诵:"A guard that asserts shape can be green and prove nothing; a guard that asserts the consequence can be red and prove the finding wrong. Both directions are worth having, and only the second one catches a bad diagnosis."
7.4 三实例:guard 像 pin 却什么都没断言
- StorageSystemTest(2026-09-23 A-1):它守卫的修复让 fixture 自己不再复现条件——不消毒时
"sub/dir/pack.zip"会让transferTo抛NoSuchFileException,但修复把名字缩减为"pack.zip"后写入直接成功。断言通过是因为"没出问题",而不是因为"失败被包住了"。修复:让写入与文件名无关地真正失败(把存储根指向一个普通文件)。 - Settings guard(2025-09-25):发布的默认值等于代码的兜底值时,值断言是盲的。
PackVariablesanchor:lastOrNull掩盖了缺失的^。
文档的结论:区分真 pin 与装饰性 guard 的唯一方法,是把它运行在一个故意破坏的实现上。2026-09-23 的记录补充道:"本轮有三个 guard 因为错误的原因通过,变异验证找到了全部三个——读取一个都没找到。这是本仓库日志中同一失败模式的第四例,唯一抓到过它的技术是破坏生产代码并观察。"
八、实测优于推理:两个测量实例
除前文的 protects() 测量与 fabric-api 嵌套测量外,2026-09-11 迭代 1 还有一个方法论级别的教训:每次 pin 都在其自身提交处重新运行——这暴露了一个不编译的 pin(详见 REFACTOR-AUDIT.md 的表格)。"full build green" 的声明可能因 Gradle 的 UP-TO-DATE 检查而失真:./gradlew build 让未改动的模块测试 UP-TO-DATE,跨模块 guard 只有在其所在模块输入变化时才真正运行(B4 案例:KDocAttachmentTest 住在 -api,而它失败的孤立 KDoc 块在插件模块)。结论:跨模块 guard 的有效性取决于它所在的模块,--rerun-tasks 或显式运行该模块套件才是真正在提问。
九、可复用的审计检查清单
从十二轮审计中沉淀出的、可迁移到任何 Kotlin/JVM 项目的检查项:
- 手工字段映射逐字段断言:复制 N 个字段的代码必须用 N 个不同哨兵值驱动,杜绝等值不可检测的交换。
- 顺序/阶梯/优先级必须有 pin:任何"第一优先、其次、再次"的链式偏好,都要有至少一个测试把相邻两臂分开,且对调两臂做变异验证。
- 枚举驱动的 guard 从
entries派生:手写listOf(...)的断言会随枚举扩展悄悄失效。 - 纯决策直接单测:分类、归因、原因函数不要只通过集成路径间接覆盖。
- 全函数检查:
first { }、firstOrNull链、空集合上的entries.first都是非全函数地雷;不可达不等于无害。 - "guard 为什么通过"与"为什么失败"同等重要:fixture 不再复现条件时,guard 只是装饰。
- 变异验证必须可编译:先清
build/test-results,把"无结果"与"零红"区分开。 - 测试与实现分离的提交卫生:
fix:之前应有独立的红色test:;测试与生产代码不要混在同一个提交里(L-2,2026-09-05)。 - 跨模块 guard 的时效性:A 模块的 guard 覆盖 B 模块的代码时,绿色
build在 A 的输入变化前不说明任何问题。 - 文档声明要写进测试:KDoc 声称的排序、线程安全、"never empty"、安全属性,每一条都需要对应的断言,否则就是会误导后人的 prose(A3 的假注释、B1 的假接线、A5 的 locale 假说)。
十、规模演进与结论
文档中的套件数字本身就是测试深度实践的成果:clientside 从 369 → 438 → 515 → 554 → 566 → 568 → 523,grinder 从 495 → 501 → 503 → 512 → 514,plugin-grinder 从 44 → 69 → 73 → 90,api 从 405 → 407 → 412 → 413 → 421,app 稳定在 149。至 2026-09-20 第三遍结束时全仓 1,910 测试、0 失败(30 个跳过均为既有 skip)。
ANALYSIS-AUDIT.md 的最终价值不在于"这个仓库没有 bug",而在于它建立了一套可证明的防御体系:每个 guard 都经过变异验证证明有牙齿,每个"看起来像问题"的疑点要么被修复、要么被记录为"已验证干净"并禁止翻案,每一条撤回与反转都被当作教训写下来。对于想要在自己的项目中复刻这套实践的工程师,文档中反复出现的三句话就是方法论的全部:
- "Ask why a guard passed, not only why it failed."——问 guard 为什么通过,而不只是为什么失败。
- "Mutation is the only way guards have been shown to have teeth."——只有变异验证能证明 guard 有牙齿。
- "Measure before optimising, and record the negative result."——优化前先测量,并记录负面结果。